Gitattributes File Format

Overview

The Gitattributes format is a Git configuration file that allows you to specify attributes for pathnames in a Git repository. This file controls how Git handles line endings, diff algorithms, merge strategies, text encoding, and other file-specific behaviors. It provides fine-grained control over Git's treatment of different file types within a repository.

Technical Details

File Characteristics

• Extension: .gitattributes
• MIME Type: text/plain
• Category: Config
• Format Type: Plain text configuration

File Locations

• Repository Root: .gitattributes (applies to entire repository)
• Subdirectories: .gitattributes in any directory (applies to that directory and subdirectories)
• Global: ~/.config/git/attributes (applies to all repositories for user)
• System: /etc/gitattributes (applies system-wide)

Syntax and Structure

Basic Syntax

# Pattern followed by attribute assignments
pattern attr1 attr2=value -attr3

# Comments start with #
# Blank lines are ignored

# Examples:
*.txt text
*.jpg binary
*.sh text eol=lf
*.bat text eol=crlf
docs/ linguist-documentation

Pattern Matching

# Exact filename
README.md text

# Wildcard patterns
*.js text
*.min.js binary

# Directory patterns
docs/ linguist-documentation
src/**/*.py text

# Negation
!important.log

# Character classes
*.[ch] text
test[0-9].txt text

# Recursive directory matching
**/logs/ export-ignore

Common Attributes

Text Handling

# Mark files as text (enable line ending normalization)
*.txt text
*.md text
*.yml text
*.json text

# Mark files as binary (disable line ending conversion)
*.png binary
*.jpg binary
*.gif binary
*.pdf binary
*.exe binary

# Auto-detect text files (Git's default behavior)
* text=auto

# Prevent normalization for specific files
sensitive.txt -text

Line Ending Control

# Force LF line endings in repository and working directory
*.sh text eol=lf
*.py text eol=lf
Makefile text eol=lf

# Force CRLF line endings
*.bat text eol=crlf
*.cmd text eol=crlf

# Use native line endings (LF on Unix, CRLF on Windows)
*.txt text eol=native

# Mixed approach for cross-platform development
# Store as LF in repository, checkout as native
*.c text
*.h text
*.cpp text eol=lf

Language Detection

# Override GitHub language detection
*.js linguist-language=JavaScript
*.ts linguist-language=TypeScript
*.vue linguist-language=Vue

# Mark as documentation (excluded from language stats)
docs/ linguist-documentation
*.md linguist-documentation
LICENSE linguist-documentation

# Mark as generated code
dist/ linguist-generated
build/ linguist-generated
*.min.js linguist-generated

# Mark as vendored (third-party code)
vendor/ linguist-vendored
node_modules/ linguist-vendored
lib/third-party/ linguist-vendored

# Exclude from language detection
*.sql linguist-detectable=false

Export and Archive Control

Export Ignore

# Exclude files from git archive
.gitattributes export-ignore
.gitignore export-ignore
.github/ export-ignore
tests/ export-ignore
docs/ export-ignore
*.test export-ignore

# Development and build files
Makefile export-ignore
*.config.js export-ignore
webpack.config.js export-ignore
jest.config.js export-ignore

# CI/CD configuration
.travis.yml export-ignore
.github/ export-ignore
.gitlab-ci.yml export-ignore

Export Substitution

# Substitute variables during export
version.txt export-subst

# In version.txt file:
# Version: $Format:%H$
# Date: $Format:%ci$
# This will be replaced with actual commit hash and date

Diff and Merge Configuration

Custom Diff Drivers

# Use specific diff algorithms
*.pdf diff=pdf
*.docx diff=word
*.xlsx diff=excel

# Text files with special handling
*.xml diff=xml
*.json diff=json

# Binary files that should show no diff
*.db -diff
*.cache -diff

# Functional diff for programming languages
*.c diff=cpp
*.h diff=cpp
*.py diff=python
*.rb diff=ruby

Merge Strategies

# Never merge specific files (always use ours)
CHANGELOG.md merge=ours
version.h merge=ours

# Use union merge strategy (combine both versions)
AUTHORS merge=union

# Custom merge driver
*.properties merge=properties-merge

# Don't merge binary files
*.db merge=binary
*.sqlite merge=binary

Filter Configuration

Clean and Smudge Filters

# Apply filters to remove/add content
*.secret filter=remove-secrets
*.template filter=template-processor

# Example: Remove API keys before committing
# Git config:
# git config filter.remove-secrets.clean 'sed "s/api_key=.*/api_key=REDACTED/"'
# git config filter.remove-secrets.smudge cat

# Large file handling
*.psd filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -text
*.sketch filter=lfs diff=lfs merge=lfs -text

Git LFS Integration

# Large File Storage configuration
*.zip filter=lfs diff=lfs merge=lfs -text
*.tar.gz filter=lfs diff=lfs merge=lfs -text
*.dmg filter=lfs diff=lfs merge=lfs -text
*.iso filter=lfs diff=lfs merge=lfs -text

# Media files
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text
*.avi filter=lfs diff=lfs merge=lfs -text
*.mkv filter=lfs diff=lfs merge=lfs -text

# Design files
*.psd filter=lfs diff=lfs merge=lfs -text
*.sketch filter=lfs diff=lfs merge=lfs -text
*.fig filter=lfs diff=lfs merge=lfs -text

# Archives and installers
*.msi filter=lfs diff=lfs merge=lfs -text
*.pkg filter=lfs diff=lfs merge=lfs -text
*.deb filter=lfs diff=lfs merge=lfs -text
*.rpm filter=lfs diff=lfs merge=lfs -text

Project-Specific Examples

Web Development

# HTML, CSS, JavaScript
*.html text eol=lf
*.css text eol=lf
*.scss text eol=lf
*.js text eol=lf
*.ts text eol=lf
*.json text eol=lf

# Configuration files
*.yml text eol=lf
*.yaml text eol=lf
*.toml text eol=lf
package.json text eol=lf
package-lock.json text eol=lf

# Build outputs
dist/ linguist-generated export-ignore
build/ linguist-generated export-ignore
node_modules/ linguist-vendored export-ignore

# Source maps
*.map linguist-generated

# Minified files
*.min.js linguist-generated
*.min.css linguist-generated

Data Science Project

# Python files
*.py text eol=lf
*.pyx text eol=lf
*.pxd text eol=lf
*.pxi text eol=lf

# Jupyter notebooks
*.ipynb text

# Data files
*.csv text
*.tsv text
*.json text
*.xml text

# Binary data files
*.pkl filter=lfs diff=lfs merge=lfs -text
*.h5 filter=lfs diff=lfs merge=lfs -text
*.hdf5 filter=lfs diff=lfs merge=lfs -text
*.npz filter=lfs diff=lfs merge=lfs -text

# Model files
*.model filter=lfs diff=lfs merge=lfs -text
*.joblib filter=lfs diff=lfs merge=lfs -text

# Images and plots
*.png filter=lfs diff=lfs merge=lfs -text
*.pdf filter=lfs diff=lfs merge=lfs -text

# Documentation
docs/ linguist-documentation
*.md linguist-documentation

Mobile Development

# iOS
*.swift text eol=lf
*.m text eol=lf
*.h text eol=lf
*.storyboard text eol=lf
*.xib text eol=lf
*.plist text eol=lf

# Android
*.java text eol=lf
*.kt text eol=lf
*.xml text eol=lf
*.gradle text eol=lf
*.properties text eol=lf

# React Native
*.js text eol=lf
*.jsx text eol=lf
*.ts text eol=lf
*.tsx text eol=lf

# Binary assets
*.png binary
*.jpg binary
*.gif binary
*.webp binary
*.ico binary

# Archives and builds
*.ipa filter=lfs diff=lfs merge=lfs -text
*.apk filter=lfs diff=lfs merge=lfs -text
*.aab filter=lfs diff=lfs merge=lfs -text

Advanced Configuration

Conditional Attributes

# Different handling based on path
src/**/*.js text eol=lf linguist-language=JavaScript
test/**/*.js text eol=lf linguist-language=JavaScript linguist-documentation
docs/**/*.js text eol=lf linguist-documentation

# Platform-specific files
*.sh text eol=lf
*.bat text eol=crlf
*.ps1 text eol=crlf

# Environment-specific
.env.* text eol=lf
config/production.yml text eol=lf
config/development.yml text eol=lf

Custom Attributes

# Define custom attributes for project-specific handling
*.config custom-config
*.template custom-template

# These can be used in scripts:
# git ls-files | git check-attr --stdin custom-config

Best Practices

Repository Setup

# Comprehensive .gitattributes for new repository
# Handle line endings consistently
* text=auto eol=lf

# Explicitly declare text files
*.txt text
*.md text
*.yml text
*.yaml text
*.json text
*.xml text
*.html text
*.css text
*.js text
*.py text
*.rb text
*.php text
*.java text
*.c text
*.h text
*.cpp text
*.hpp text

# Explicitly declare binary files
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.tar.gz binary
*.exe binary
*.dll binary
*.so binary
*.dylib binary

# Archives and packages
*.7z binary
*.dmg binary
*.gz binary
*.iso binary
*.jar binary
*.rar binary
*.tar binary
*.zip binary

# Exclude from exports
.gitattributes export-ignore
.gitignore export-ignore
.github/ export-ignore

Troubleshooting

# Check attributes for files
git check-attr --all README.md
git check-attr text *.js

# List files with specific attributes
git ls-files | git check-attr --stdin text

# Refresh line endings after changing attributes
git rm --cached -r .
git reset --hard

Team Collaboration

• Commit .gitattributes to ensure consistent behavior across team
• Document custom attributes and filters in project README
• Test attribute changes on different platforms before committing
• Use explicit binary marking for ambiguous file types

The Gitattributes format provides powerful control over Git's file handling, enabling consistent cross-platform development and specialized treatment of different file types within repositories.