{"thread":{"id":"65632","subject":"[PATCH] doc: clarify that --word-diff operates on line-level hunks","startedAt":"2026-05-13T15:42:43Z","lastAt":"2026-05-28T19:21:48Z","messageCount":2,"participants":["Michael Montalbo via GitGitGadget"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"543245","messageId":"pull.2113.git.1778686956622.gitgitgadget@gmail.com","threadId":"65632","inReplyTo":null,"subject":"[PATCH] doc: clarify that --word-diff operates on line-level hunks","fromName":"Michael Montalbo via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-13T15:42:36Z","receivedAt":"2026-05-13T15:42:43Z","isPatch":true,"body":"From: Michael Montalbo <mmontalbo@gmail.com>\n\nThe --word-diff documentation describes the output modes and\nword-regex mechanics but does not explain that word-diff operates\nwithin the hunks produced by the line-level diff rather than\nperforming an independent word-stream comparison.  This can\nsurprise users when the line-level alignment causes word-level\nchanges to appear even though the words in both files are\nidentical.\n\nAdd a short note explaining the two-stage relationship.\n\nSigned-off-by: Michael Montalbo <mmontalbo@gmail.com>\n---\n    doc: clarify that --word-diff operates on line-level hunks\n    \n    CC: Vincent Lefevre vincent@vinc17.net, Johannes Sixt j6t@kdbg.org\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2113\n\n Documentation/diff-options.adoc | 5 +++++\n 1 file changed, 5 insertions(+)\n\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex 8a63b5e164..665473e61a 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -457,6 +457,11 @@ endif::git-diff[]\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n++\n+Word diff works by finding word-level changes within each hunk of\n+the line-level diff.  The line-level alignment determines which\n+changed lines are compared to each other, which can affect the\n+word-level output.\n \n `--word-diff-regex=<regex>`::\n \tUse _<regex>_ to decide what a word is, instead of considering\n\nbase-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0\n-- \ngitgitgadget\n"},{"id":"544232","messageId":"pull.2113.v2.git.1779996106005.gitgitgadget@gmail.com","threadId":"65632","inReplyTo":"pull.2113.git.1778686956622.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: clarify that --word-diff operates on line-level hunks","fromName":"Michael Montalbo via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2026-05-28T19:21:45Z","receivedAt":"2026-05-28T19:21:48Z","isPatch":true,"body":"From: Michael Montalbo <mmontalbo@gmail.com>\n\nThe --word-diff documentation describes the output modes and\nword-regex mechanics but does not explain that word-diff operates\nwithin the hunks produced by the line-level diff rather than\nperforming an independent word-stream comparison.  This can\nsurprise users when the line-level alignment causes word-level\nchanges to appear even though the words in both files are\nidentical.\n\nAdd an implementation note explaining the two-stage relationship\nand that the output may change if Git acquires a different\nimplementation in the future.\n\nSigned-off-by: Michael Montalbo <mmontalbo@gmail.com>\n---\n    doc: clarify that --word-diff operates on line-level hunks\n    \n    CC: Vincent Lefevre vincent@vinc17.net, Johannes Sixt j6t@kdbg.org\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2113\n\nRange-diff vs v1:\n\n 1:  73f7b06c06 ! 1:  bc5ca5a147 doc: clarify that --word-diff operates on line-level hunks\n     @@ Commit message\n          changes to appear even though the words in both files are\n          identical.\n      \n     -    Add a short note explaining the two-stage relationship.\n     +    Add an implementation note explaining the two-stage relationship\n     +    and that the output may change if Git acquires a different\n     +    implementation in the future.\n      \n          Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>\n      \n     @@ Documentation/diff-options.adoc: endif::git-diff[]\n       Note that despite the name of the first mode, color is used to\n       highlight the changed parts in all modes if enabled.\n      ++\n     -+Word diff works by finding word-level changes within each hunk of\n     -+the line-level diff.  The line-level alignment determines which\n     -+changed lines are compared to each other, which can affect the\n     -+word-level output.\n     ++The `--word-diff` option operates by taking the same line-by-line\n     ++diff that is produced without the option and computing\n     ++word-by-word changes within each hunk.  This may produce a\n     ++larger diff than a dedicated word-diff tool would.  If Git\n     ++acquires a different implementation in the future, the output\n     ++may change.  Note that this is similar to the `--diff-algorithm`\n     ++option, which may also change the output.\n       \n       `--word-diff-regex=<regex>`::\n       \tUse _<regex>_ to decide what a word is, instead of considering\n\n\n Documentation/diff-options.adoc | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex 8a63b5e164..c8242e2462 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -457,6 +457,14 @@ endif::git-diff[]\n +\n Note that despite the name of the first mode, color is used to\n highlight the changed parts in all modes if enabled.\n++\n+The `--word-diff` option operates by taking the same line-by-line\n+diff that is produced without the option and computing\n+word-by-word changes within each hunk.  This may produce a\n+larger diff than a dedicated word-diff tool would.  If Git\n+acquires a different implementation in the future, the output\n+may change.  Note that this is similar to the `--diff-algorithm`\n+option, which may also change the output.\n \n `--word-diff-regex=<regex>`::\n \tUse _<regex>_ to decide what a word is, instead of considering\n\nbase-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0\n-- \ngitgitgadget\n"}]}