From 240662ef2da8f5609a5c07068e3c2016d830e3b4 Mon Sep 17 00:00:00 2001 From: Michael Montalbo Date: Sat, 1 Aug 2026 10:41:44 -0700 Subject: [PATCH] gitattributes: document how external diff drivers relate to diff features The "Defining an external diff driver" section explains how to configure diff..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 Signed-off-by: Junio C Hamano --- Documentation/gitattributes.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Documentation/gitattributes.adoc b/Documentation/gitattributes.adoc index bd76167a45..da773e2924 100644 --- a/Documentation/gitattributes.adoc +++ b/Documentation/gitattributes.adoc @@ -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