In Git, what does a .gitattributes file control, and how are its rules resolved?

## What the file is for Most Git configuration is repository-wide or user-wide. `.gitattributes` is the mechanism for saying "this rule applies to these paths". It is how a repository declares that `*.png` is not worth diffing, that `CHANGELOG.md` should merge by union, that `*.docx` needs a text conversion before display, or that a `.github/` directory should not appear in an exported archive. ## Syntax A line is a pattern followed by one or more attributes. The pattern dialect is the same as `.gitignore`: no slash means match the name at any depth, a slash anchors to the directory containing the file, `*` does not cross a separator, `**` does. Attributes take four states: - `text` sets the attribute. - `-diff` unsets it. - `diff=pdf` sets it to a value, usually naming a driver. - `!merge` makes it *unspecified*, deliberately clearing any value a lower-precedence file assigned. Comments begin with `#`. Macro attributes, written `[attr]name attr1 -attr2`, expand to a bundle; Git ships one built-in macro, `binary`, and custom macros may only be defined in a top-level attributes file. ## Precedence For a given path Git consults, from highest precedence to lowest: `$GIT_DIR/info/attributes`, then the `.gitattributes` in the path's own directory, then those in each parent directory up to the top of the work tree (nearer wins), then the per-user file named by `core.attributesFile`, then the system-wide file. Note the contrast with ignore rules, where the repository-local `info/exclude` sits *below* committed files. Here the local override wins, which makes `info/attributes` a useful escape hatch for one clone. Within a single file, evaluation is last-match-wins, so a broad line at the bottom silently overrides more specific lines above it. ## The split that surprises people `.gitattributes` is committed, so the *assignment* travels with the repository. But an assignment such as `*.pdf diff=pdf` only names a driver; the driver itself is defined in config, for example `diff.pdf.textconv`, and config is per-machine and not versioned. A teammate who clones the repository gets the attribute and none of the behaviour. Anything you rely on must therefore either use a built-in behaviour that needs no config (`-diff`, `binary`, `merge=union`, `export-ignore`) or come with setup instructions, a bootstrap script, or a documented onboarding step. ## Inspecting `git check-attr -a -- path/to/file` lists every attribute in effect for a path, and `git check-attr diff -- path` asks about one. The output names the attribute and its resolved value, which is the fastest way to confirm that the line you wrote is the line that is winning. It is the direct analogue of `git check-ignore -v` for this file. ## When new rules take effect Attributes affect operations as they happen: a diff you run now, a merge you start now, an archive you create now. They do **not** retroactively change blobs already stored. Adding a filter or a text attribute does not reprocess files that are already in the index and the working tree; the content only passes through the new rules the next time it goes into or out of the repository. That is why changing attributes is usually paired with a deliberate re-checkout or re-add of the affected paths. ## Attributes Git does not interpret Unknown attribute names are legal and simply carried; Git assigns them and does nothing else. That is how hosting and analysis tools piggyback on the file, for instance the `linguist-` family of attributes, which Git itself never acts on. Reading such a line tells you the behaviour it triggers is implemented by some other tool, not by Git. ## Small file, large blast radius Because a single pattern can change how every merge of a file type behaves for every contributor, `.gitattributes` deserves the same review attention as build configuration. A stray `-diff` on a source glob makes reviews unreadable; a stray `binary` on text makes merges conflict wholesale.