[PATCH v2] doc: clarify that --word-diff operates on line-level hunks
- From
Michael Montalbo via GitGitGadget <gitgitgadget@gmail.com>
- Date
- May 28, 2026, 19:21 UTC
- Message-ID
- <pull.2113.v2.git.1779996106005.gitgitgadget@gmail.com>
- In-Reply-To
- <pull.2113.git.1778686956622.gitgitgadget@gmail.com>
From: Michael Montalbo <mmontalbo@gmail.com>
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>
---
doc: clarify that --word-diff operates on line-level hunks
CC: Vincent Lefevre vincent@vinc17.net, Johannes Sixt j6t@kdbg.orgPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v2 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v2 Pull-Request: https://github.com/gitgitgadget/git/pull/2113
Range-diff vs v1:
1: 73f7b06c06 ! 1: bc5ca5a147 doc: clarify that --word-diff operates on line-level hunks
@@ Commit message
changes to appear even though the words in both files are
identical.
- Add a short note explaining the two-stage relationship.
+ 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>
@@ Documentation/diff-options.adoc: 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.
++
-+Word diff works by finding word-level changes within each hunk of
-+the line-level diff. The line-level alignment determines which
-+changed lines are compared to each other, which can affect the
-+word-level output.
++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=<regex>`::
Use _<regex>_ to decide what a word is, instead of consideringDocumentation/diff-options.adoc | 8 ++++++++ 1 file changed, 8 insertions(+)
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index 8a63b5e164..c8242e2462 100644 --- a/Documentation/diff-options.adoc +++ b/Documentation/diff-options.adoc @@ -457,6 +457,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=<regex>`:: Use _<regex>_ to decide what a word is, instead of considering base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
-- gitgitgadget