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 <mmontalbo@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Montalbo committed
May 28, 2026 at 19:21 UTC
1ec041bebb46159562c4beeb2e6980284e0f9a28
1 file changed
+8
Documentation/diff-options.adoc
+8
@@ -455,6 +455,14 @@ endif::git-diff[]
455
+
456
Note that despite the name of the first mode, color is used to
457
highlight the changed parts in all modes if enabled.
458
++
459
+The `--word-diff` option operates by taking the same line-by-line
460
+diff that is produced without the option and computing
461
+word-by-word changes within each hunk. This may produce a
462
+larger diff than a dedicated word-diff tool would. If Git
463
+acquires a different implementation in the future, the output
464
+may change. Note that this is similar to the `--diff-algorithm`
465
+option, which may also change the output.
466
467
`--word-diff-regex=<regex>`::
468
Use _<regex>_ to decide what a word is, instead of considering