From: Johannes Sixt Date: Mon, 18 May 2026 07:30:03 GMT Subject: Re: [BUG] "git diff --word-diff" gives a diff while they are only space changes Message-ID: <89224cb5-27b1-45b6-93d8-a0ad5e2447a2@kdbg.org> In-Reply-To: Am 18.05.26 um 05:30 schrieb Michael Montalbo: > On Thu, May 14, 2026 at 12:37 AM Junio C Hamano wrote: >> >> Michael Montalbo writes: >> >>> @@ -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. >> >> The added text may not say anything wrong, but I am not sure how it >> helps the end user to know the way machinery works internally. >> > > I see what you mean. Maybe the doc should focus more on calling out > the user-facing implication: > > `--word-diff` finds word-level changes within each hunk of the > line-level diff, so changes that only affect whitespace may still > appear in the output. I don't know what this paragraph is trying to explain. I don't see how this would explain Vincent's observed word-diff. The thing is, "word-diff" is such a descriptive name for the operation that it is difficult to find a description that is even better. The manual page doesn't even give it a try. It defers to --word-diff-regex right away, which then only talks about low-level details and doesn't attempt to give a higher-level description what a word-diff is. I don't think you can summarize the algorithm in a single sentence. But then I have to ask: why write it down anyway? How does it help the reader? Only so that they are able to derive an explanation for a particular observed output? Would it have saved Vincent to write a bug report? If we document the algorithm in such detail, we cast it in stone. I wouldn't want to paint ourselves into that corner. -- Hannes