.gitattributes Explainer · guide

Why is my .gitattributes not working? Five lines git ignores

Git rarely complains about a .gitattributes line it cannot use. Most of the time it does nothing, or prints one warning during an unrelated command and moves on. These are the five causes we see, each shown with what git check-attr -a (git 2.43) printed for it. The explainer finds the first four in a pasted file and shows which line set each attribute of every path.

1. A trailing slash: docs/ matches the folder, not the files

$ cat .gitattributes
docs/ linguist-documentation
$ git check-attr -a docs/guide.md docs/
docs/: linguist-documentation: set

Nothing is printed for docs/guide.md. Attributes are looked up for each file, and a pattern ending in / only matches folders, so the folder gets the attribute and no file does. Write docs/** linguist-documentation. The exception is export-ignore: git archive checks folders, so docs/ export-ignore does leave the folder out of an archive (and, unlike docs/**, leaves no empty folder behind).

2. A ! pattern: the whole line is dropped

vendor/** linguist-vendored
!vendor/ours/** linguist-vendored
warning: Negative patterns are ignored in git attributes
Use '\!' for literal leading exclamation.

Unlike .gitignore, attribute files have no negative patterns. To take a path out of a broad rule, add a later line for it that changes the attribute: vendor/ours/** -linguist-vendored (unset) or vendor/ours/** !linguist-vendored (back to unspecified; the ! goes on the attribute, not the pattern).

3. An [attr] macro in a subfolder

$ cat web/.gitattributes
[attr]generated linguist-generated -diff
*.snap generated
$ git check-attr -a web/app.snap
[attr]generated linguist-generated -diff not allowed: web/.gitattributes:1
web/app.snap: generated: set

Macros are read only from the top-level .gitattributes, .git/info/attributes and the global and system files. In a subfolder git skips the definition, and *.snap generated then sets an attribute called generated that nothing reads. Move the [attr] line to the root file.

4. One invalid name, or a value git does not know

*.z a/b ok
a/b is not a valid attribute name: .gitattributes:1
*.bat text eol=CRLF
a.bat: eol: CRLF        (set, but git converts only for eol=crlf)

Names may use letters, digits, -, . and _, and one bad name drops every attribute on the line. Values are compared exactly: git understands eol=lf and eol=crlf in lower case, and text, -text, text=auto; eol=CRLF and text=true are stored but ignored, and ls-files --eol shows the difference (attr/text instead of attr/text eol=crlf). Names are case-sensitive too: Diff=html is not diff=html. A pattern containing a space needs double quotes, or the rest of the name is read as an attribute.

5. Files committed before the rule

Line-ending rules act when git stores or checks out a file, so a file committed with CRLF before you added * text=auto stays CRLF in the repository. Re-store everything under the new rules and commit:

git add --renormalize .
git commit -m "Normalize line endings"

This command comes from the gitattributes manual. For Git LFS, the same applies to files committed before git lfs track; that needs git lfs migrate, which rewrites history, so read its documentation first.

How git picks the winning line

For each attribute separately, the first line that decides it wins, read in this order: .git/info/attributes; the .gitattributes in the file's own folder, then each parent up to the root; the global file (core.attributesFile, by default ~/.config/git/attributes); the system file. Inside a file the last matching line wins, and on one line a later attribute beats an earlier one, so *.png text binary leaves text unset while *.png binary text leaves it set. The explainer lists every matching line for a path in exactly that order.

Why is docs/ linguist-documentation not working?

Because a pattern that ends in a slash matches only the folder itself, and attributes are looked up for each file. docs/ linguist-documentation gives the folder docs the attribute and none of the files inside it. Write docs/** linguist-documentation instead. The one attribute that does work on a folder pattern is export-ignore, because git archive checks folders.

Can I use ! in .gitattributes like in .gitignore?

No. A line whose pattern starts with ! is dropped with the warning Negative patterns are ignored in git attributes. To exempt a path, add a later line for it that switches the attribute off with a minus, or back to unspecified with an exclamation mark in front of the attribute name rather than the pattern.

Why does git say [attr] not allowed?

Macro definitions such as [attr]generated linguist-generated -diff are only read from the top-level .gitattributes, .git/info/attributes and the global and system attribute files. In a .gitattributes inside a subfolder git prints not allowed and skips the line, and lines that use the macro name then set only an attribute of that name.

Why did changing text or eol in .gitattributes not change my files?

Git applies line-ending rules when it stores or checks out a file, so files already committed keep what they were stored with. Run git add --renormalize . and commit, then check the files out again. Also check the spelling: eol=CRLF and text=true are not values git knows, and git ignores them.