.gitattributes: line endings, diff drivers, merge drivers and export-ignore

What it is

.gitattributes maps path patterns to attributes, in the same pattern syntax as .gitignore, and is versioned with the code. The most used attributes, as described in the documentation:

• text / text=auto / -text: whether Git converts line endings on check-in (to LF in the repository). With text=auto Git decides per file whether it is text.
• eol=lf / eol=crlf: the line ending in the working tree on checkout; setting eol also sets text.
• binary: a built-in macro equal to -diff -merge -text.
• diff=<driver>: selects a diff driver configured under [diff "<driver>"], for example xfuncname to choose the hunk-header line, or textconv to turn a binary format into text for viewing.
• merge=<driver>: text (normal three-way), binary (keep our version, leave conflicted), union (take lines from both, order not guaranteed) or a custom driver from .git/config.
• export-ignore: the path is left out of git archive; export-subst expands $Format:...$ placeholders in archived files.

Why it matters

Without a committed policy, every developer's core.autocrlf decides, and mixed line endings turn one-line fixes into whole-file diffs. Diff and merge drivers make generated or structured files reviewable and reduce false conflicts. export-ignore keeps tests and CI configuration out of release tarballs.

How to apply

• Start with * text=auto, then pin exceptions: *.sh text eol=lf, *.bat text eol=crlf, *.png binary.
• After adding or changing line-ending rules, run git add --renormalize . from a clean tree and commit the normalisation alone, as the documentation's example shows.
• Give lock files or changelogs merge=union only if line order truly does not matter; the documentation warns the result must be verified.
• Enable the built-in hunk-header patterns the documentation lists (*.py diff=python, *.tex diff=tex) so reviews show the enclosing function, and define an xfuncname driver only for languages without one.
• Mark tests/ export-ignore and .github/ export-ignore when git archive produces your source releases.

Pitfalls

Git consults $GIT_DIR/info/attributes first, then the .gitattributes files from the path's directory up to the top level; a clone applies new rules only once it has the commit that adds them, and files already checked out keep their old line endings until renormalised. Macros like binary can be defined only in top-level attribute files. textconv output is one-way and cannot be applied as a patch. Custom drivers live in each user's config, so the attribute alone does nothing on a machine that lacks the driver.