git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH] doc: clarify that --word-diff operates on line-level hunks

From
Michael Montalbo via GitGitGadget <gitgitgadget@gmail.com>
Date
May 13, 2026, 15:42 UTC
Message-ID
<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 a short note explaining the two-stage relationship.
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.org
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2113%2Fmmontalbo%2Fmm%2Fdoc-word-diff-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2113/mmontalbo/mm/doc-word-diff-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2113
 Documentation/diff-options.adoc | 5 +++++
 1 file changed, 5 insertions(+)
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index 8a63b5e164..665473e61a 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -457,6 +457,11 @@ 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.
 
 `--word-diff-regex=<regex>`::
 	Use _<regex>_ to decide what a word is, instead of considering

base-commit: 94f057755b7941b321fd11fec1b2e3ca5313a4e0
-- 
gitgitgadget
Next: Michael Montalbo via GitGitGadget
Message 1 of 2 in “doc: clarify that --word-diff operates on line-level hunks”
  1. doc: clarify that --word-diff operates on line-level hunksMichael Montalbo via GitGitGadget, May 13, 2026
  2. doc: clarify that --word-diff operates on line-level hunksMichael Montalbo via GitGitGadget, May 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.