Re: [BUG] "git diff --word-diff" gives a diff while they are only space changes

From: Johannes Sixt <j6t@kdbg.org>
Date: May 18, 2026, 07:30 UTC
Message-ID: <89224cb5-27b1-45b6-93d8-a0ad5e2447a2@kdbg.org>
In-Reply-To: <CAC2QwmKORPnsmV4SM_CnmhrbF+X754ae-n9m1fgjvVsL9d-wzg@mail.gmail.com>

Am 18.05.26 um 05:30 schrieb Michael Montalbo:

Show 24 quoted lines

> On Thu, May 14, 2026 at 12:37 AM Junio C Hamano <gitster@pobox.com> wrote:
>>
>> Michael Montalbo <mmontalbo@gmail.com> 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