From: Michael Montalbo <mmontalbo@gmail.com>
Date: Tue, 19 May 2026 02:07:21 GMT
Subject: Re: [BUG] "git diff --word-diff" gives a diff while they are only space changes
Message-ID: <CAC2Qwm+BLNf-2kvePKNF-FKQX3raOBzSRmwd0ZEdzmo8TqkMGA@mail.gmail.com>
In-Reply-To: <89224cb5-27b1-45b6-93d8-a0ad5e2447a2@kdbg.org>

On Mon, May 18, 2026 at 12:30 AM Johannes Sixt <j6t@kdbg.org> wrote:
>
> Am 18.05.26 um 05:30 schrieb Michael Montalbo:
> > 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.
>

Yeah, I was trying to explain the difference Vincent saw compared to wdiff,
but I agree with your criticism. In "beating around the bush" regarding
implementation details / making a direct comparison to wdiff, it has been
hard to craft a meaningful message.

> 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.
>

I also agree with this sentiment. I haven't been able to come up with a
message that threads the needle appropriately, so I'm open to dropping
the patch or reworking it if others have suggestions.

> -- Hannes
>