.gitattributes

Definition

A .gitattributes file tells Git how to treat specific files based on their path. Where .gitignore decides whether Git tracks a file, .gitattributes decides how Git handles the files it does track — how to normalize line endings, how to diff them, how to merge them, and what to do at export time. It lives in your repository and is committed, so every collaborator gets the same behavior.

How it works

Each line pairs a file pattern with one or more attributes:

# pattern        attributes
*.txt            text
*.png            binary
*.sh             text eol=lf

Patterns follow the same glob rules as .gitignore. The attributes after the pattern control specific Git behaviors for matching files.

Normalizing line endings

The most common use of .gitattributes is ending the "every line changed" mess that happens when Windows and Unix developers share a repo. Marking files as text lets Git normalize line endings to LF in the repository and convert them on checkout:

* text=auto
*.sh text eol=lf
*.bat text eol=crlf

text=auto lets Git decide which files are text; the explicit eol settings force a specific ending for files that need one. This is more reliable than relying on each developer's core.autocrlf setting.

Marking files as binary

Telling Git a file is binary stops it from trying to show a textual diff or merge it line by line:

*.pdf binary
*.png binary

The binary attribute is shorthand for -text -diff, which disables line-ending conversion and textual diffing.

Custom diff and merge behavior

.gitattributes can route certain files through custom diff or merge drivers. For example, you can tell Git to always take your side when merging a generated file:

package-lock.json merge=ours

Or label a file type so diffs show meaningful hunk headers. These advanced uses make code review clearer for non-obvious file formats.

Export-ignore

When someone downloads a release archive via git archive, you often want to leave out development files. The export-ignore attribute does exactly that:

/tests       export-ignore
/.github     export-ignore
.gitattributes export-ignore

Common attributes

Practice