gitattributes: document how external diff drivers relate to diff features

The "Defining an external diff driver" section explains how to
configure diff.<driver>.command but not how the driver relates to the
rest of Git's diff machinery.  In particular, the command only
replaces the textual patch: word diff, function context, color, and
the like cannot apply to its output, while the summary formats, blame,
and git log -L do not run it at all and keep using the builtin diff.

Spell this out so the scope of an external diff driver is clear.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Michael Montalbo
2026-08-01 10:41:44 -07:00
committed by Junio C Hamano
parent 815d4fcc2a
commit 240662ef2d

View File

@@ -784,6 +784,17 @@ with the above configuration, i.e. `j-c-diff`, with 7
parameters, just like `GIT_EXTERNAL_DIFF` program is called.
See linkgit:git[1] for details.
An external diff driver replaces the patch Git would otherwise
produce for the path: Git runs the command and shows its output in
place of its own. Output features that post-process Git's diff do
not apply to the driver's output; word diff, function context (`-W`),
`--color-moved`, and coloring all act on Git's builtin diff, not the
driver's output.
The driver is consulted only when Git generates a textual patch. The
summary formats (`--stat`, `--numstat`, `--shortstat`, and
`--dirstat`), `git blame`, and `git log -L` do not run it and
continue to use Git's builtin diff.
If the program is able to ignore certain changes (similar to
`git diff --ignore-space-change`), then also set the option
`trustExitCode` to true. It is then expected to return exit code 1 if