Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

The diff and merge attributes

Reference for the diff and merge attributes in .gitattributes: binary files, custom diff drivers, textconv, hunk headers, merge=union and custom merge drivers.

The diff and merge attributes choose how Git compares and merges particular paths. With them you can mark a file as binary, give it a readable text view for diffs (textconv), improve the hunk headers for a language, or merge it with a special rule such as "keep both sides".

Both attributes name a driver. A driver's behavior is defined in your configuration under [diff "<name>"] or [merge "<name>"], so the attribute file can be committed while the commands stay on each machine.

Terminal
*.pdf   diff=pdf
*.md    diff=markdown
*.lock  -diff merge=binary
CHANGELOG.md merge=union

Try it

Bash textconv: readable diffs for an opaque file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash merge=union keeps both sides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
<pattern> diff            # force text diff
<pattern> -diff           # treat as binary for diffs
<pattern> diff=<driver>
<pattern> merge=<driver>  # text | binary | union | custom
<pattern> -merge
<pattern> binary          # shorthand for -diff -merge -text
Name Description
diff Always produce a text diff, even if the file looks binary.
-diff Never show a text diff; Git prints "Binary files differ".
diff=<driver> Use the settings of [diff "<driver>"]. A built-in name such as java, python, markdown, html or cpp selects better hunk-header patterns.
diff.<driver>.textconv Command that turns the file into text before diffing. Used by diff, log -p, show and blame.
diff.<driver>.xfuncname Regular expression for the line that becomes the hunk header.
diff.<driver>.binary Treat the driver's files as binary (usually combined with textconv).
-merge Never merge the contents: Git keeps the current branch's version and reports a conflict.
merge=binary Same idea, written as a driver name.
merge=union Merge as text, keeping lines from both sides without conflict markers.
merge=<name> Run the command in merge.<name>.driver, with %O (base), %A (ours, overwritten with the result) and %B (theirs).

Usage notes

  • Only the attribute is shared. textconv and custom merge.*.driver commands live in config, never in a committed file; share them with a setup script or a documented step.
  • Union is blunt. It never reports a conflict, so it suits append-only files (changelogs, ignore lists). It can duplicate or reorder lines.
  • A merge driver must exit 0 on success. A nonzero exit means "conflict", and the file in %A is left for the user.
  • Driver names must match. A typo silently falls back to the default behavior.
  • textconv changes only the display. The stored file is untouched, and git apply cannot use such a diff.
  • Needs the config on every clone. Without the [diff "b64"] section, the attribute does nothing.
  • binary is a macro. It is exactly -diff -merge -text.