From: Michael Montalbo Date: Thu, 28 May 2026 19:21:45 +0000 (+0000) Subject: doc: clarify that --word-diff operates on line-level hunks X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=1ec041bebb46159562c4beeb2e6980284e0f9a28;p=thirdparty%2Fgit.git doc: clarify that --word-diff operates on line-level hunks The --word-diff documentation describes the output modes and word-regex mechanics but does not explain that word-diff operates within the hunks produced by the line-level diff rather than performing an independent word-stream comparison. This can surprise users when the line-level alignment causes word-level changes to appear even though the words in both files are identical. Add an implementation note explaining the two-stage relationship and that the output may change if Git acquires a different implementation in the future. Signed-off-by: Michael Montalbo Signed-off-by: Junio C Hamano --- diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index 9cdad6f72a..88b724b8c6 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -455,6 +455,14 @@ endif::git-diff[] + Note that despite the name of the first mode, color is used to highlight the changed parts in all modes if enabled. ++ +The `--word-diff` option operates by taking the same line-by-line +diff that is produced without the option and computing +word-by-word changes within each hunk. This may produce a +larger diff than a dedicated word-diff tool would. If Git +acquires a different implementation in the future, the output +may change. Note that this is similar to the `--diff-algorithm` +option, which may also change the output. `--word-diff-regex=`:: Use __ to decide what a word is, instead of considering