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

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

[Vincent Lefevre]

Consider the following two 5-line files:

file1:

1
2
3
 2
4

file2:

1
 2
 3
 2
 4

On these files, "git diff --word-diff file1 file2" gives

--- a/file1
+++ b/file2
@@ -1,5 +1,5 @@
1
[-2-]
[-3-]
 2
 {+3+}
{+ 2+}
 4

instead of

--- a/file1
+++ b/file2
@@ -1,5 +1,5 @@
1
 2
 3
 2
 4

(e.g. as output by GNU wdiff 1.2.2).

Equivalently, the following command can be used under bash or zsh:

  git diff --word-diff <(printf "1\n2\n3\n 2\n4\n") \
                       <(printf "1\n 2\n 3\n 2\n 4\n")

Tested with git 2.39.5 (Debian 12), 2.53.0 (Debian unstable) and
2.54.0 (Termux/Android).

Issue initially found with

  git show --word-diff 1bf0b214deff2d0ccdcef3b2a4723369e014de3d

and more precisely

  git show --word-diff 1bf0b214deff2d0ccdcef3b2a4723369e014de3d attach.c

in the Mutt Git repository.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Johannes Sixt]

Am 06.05.26 um 03:09 schrieb Vincent Lefevre:
> Consider the following two 5-line files:
> 
> file1:
> 
> 1
> 2
> 3
>  2
> 4
> 
> file2:
> 
> 1
>  2
>  3
>  2
>  4
> 
> On these files, "git diff --word-diff file1 file2" gives
> 
> --- a/file1
> +++ b/file2
> @@ -1,5 +1,5 @@
> 1
> [-2-]
> [-3-]
>  2
>  {+3+}
> {+ 2+}
>  4
> 
> instead of
> 
> --- a/file1
> +++ b/file2
> @@ -1,5 +1,5 @@
> 1
>  2
>  3
>  2
>  4
> 
> (e.g. as output by GNU wdiff 1.2.2).

This is expected behavior.

git diff --word-diff is not agnostic to whitespace; if you drop
--word-diff, you see the line-diff that the word-diff is based on. If
you want whitespace-agnostic word-diff, you have to add -w.

-- Hannes

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

[Vincent Lefevre]

On 2026-05-08 14:48:01 +0200, Johannes Sixt wrote:
> This is expected behavior.
> 
> git diff --word-diff is not agnostic to whitespace; if you drop
> --word-diff, you see the line-diff that the word-diff is based on. If
> you want whitespace-agnostic word-diff, you have to add -w.

This is not how it is documented. Even when using "git diff" without
--word-diff, but with GNU wdiff instead, the output is fine:

$ git diff file1 file2 | wdiff -d
diff --git a/file1 b/file2
index da04344..0074613 100644
[--- a/file1-]
{+++ b/file2+}
@@ -1,5 +1,5 @@
1
 2
 3
 2
 4

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Johannes Sixt]

Am 08.05.26 um 23:39 schrieb Vincent Lefevre:
> On 2026-05-08 14:48:01 +0200, Johannes Sixt wrote:
>> This is expected behavior.
>>
>> git diff --word-diff is not agnostic to whitespace; if you drop
>> --word-diff, you see the line-diff that the word-diff is based on. If
>> you want whitespace-agnostic word-diff, you have to add -w.
> 
> This is not how it is documented. Even when using "git diff" without
> --word-diff, but with GNU wdiff instead, the output is fine:
> 
> $ git diff file1 file2 | wdiff -d
> diff --git a/file1 b/file2
> index da04344..0074613 100644
> [--- a/file1-]
> {+++ b/file2+}
> @@ -1,5 +1,5 @@
> 1
>  2
>  3
>  2
>  4

It would have helped if you had pointed to, or cited, the documentation.
I cannot find documentation from which I can derive that the above
*must* be the correct output. In particular, I don't find any mention
that --word-diff operates exactly like GNU wdiff.

-- Hannes

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

[Vincent Lefevre]

On 2026-05-09 08:16:48 +0200, Johannes Sixt wrote:
> Am 08.05.26 um 23:39 schrieb Vincent Lefevre:
> > On 2026-05-08 14:48:01 +0200, Johannes Sixt wrote:
> >> This is expected behavior.
> >>
> >> git diff --word-diff is not agnostic to whitespace; if you drop
> >> --word-diff, you see the line-diff that the word-diff is based on. If
> >> you want whitespace-agnostic word-diff, you have to add -w.
> > 
> > This is not how it is documented. Even when using "git diff" without
> > --word-diff, but with GNU wdiff instead, the output is fine:
> > 
> > $ git diff file1 file2 | wdiff -d
> > diff --git a/file1 b/file2
> > index da04344..0074613 100644
> > [--- a/file1-]
> > {+++ b/file2+}
> > @@ -1,5 +1,5 @@
> > 1
> >  2
> >  3
> >  2
> >  4
> 
> It would have helped if you had pointed to, or cited, the documentation.
> I cannot find documentation from which I can derive that the above
> *must* be the correct output. In particular, I don't find any mention
> that --word-diff operates exactly like GNU wdiff.

For wdiff, it is just described as "display word differences between
text files", and it does exactly that. For instance, if there are no
differences in words, it shows no differences.

For git with the --word-diff, there is actually no documentation,
except the use of "changed words" and "word diff". No mention of
line diff at all! So this is quite confusing.

Note: This isn't even a line-based diff with highlighted word diff
as done by some tools, such as Emacs diff-mode.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Michael Montalbo]

On Sat, 9 May 2026 17:55:26 +0200, Vincent Lefevre wrote:
> For wdiff, it is just described as "display word differences between
> text files", and it does exactly that. For instance, if there are no
> differences in words, it shows no differences.
>
> For git with the --word-diff, there is actually no documentation,
> except the use of "changed words" and "word diff". No mention of
> line diff at all! So this is quite confusing.

Maybe something like this would be worth adding to the docs:

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

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

[Vincent Lefevre]

On 2026-05-12 13:56:19 -0700, Michael Montalbo wrote:
> Maybe something like this would be worth adding to the docs:
[...]
> +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.
[...]

Yes, this would be useful.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Michael Montalbo]

On 2026-05-12 21:17 UTC, Vincent Lefevre wrote:
> Yes, this would be useful.

I've submitted a patch for this:
https://lore.kernel.org/git/pull.2113.git.1778686956622.gitgitgadget@gmail.com/T/#u

On Tue, May 12, 2026 at 2:17 PM Vincent Lefevre <vincent@vinc17.net> wrote:
>
> On 2026-05-12 13:56:19 -0700, Michael Montalbo wrote:
> > Maybe something like this would be worth adding to the docs:
> [...]
> > +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.
> [...]
>
> Yes, this would be useful.
>
> --
> Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
> 100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
> Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Junio C Hamano]

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.

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

[Vincent Lefevre]

On 2026-05-14 16:37:39 +0900, Junio C Hamano 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.

Perhaps only the first sentence should be kept and that the following
should be added: "Because of that, using the --ignore-space-change
option is recommended."

Note: Earlier in the discussion, Johannes Sixt suggested -w
(--ignore-all-space), but this is wrong, as

  git diff --word-diff -w <(printf foo) <(printf "f o o")

gives no differences while one has 1 word "foo" vs 3 words "f o o".

However, --ignore-space-change is actually not even sufficient
since

  git diff --ignore-space-change <(printf "foo bar") <(printf "foo\nbar")

finds differences though there are only space changes (thus this
may affect hunks in case --word-diff would be used too). However,
I suppose that the cases where --word-diff --ignore-space-change
would not give a "real word diff" would be quite rare in practice.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

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

[Phillip Wood]

On 14/05/2026 10:55, Vincent Lefevre wrote:
> On 2026-05-14 16:37:39 +0900, Junio C Hamano 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.
> 
> Perhaps only the first sentence should be kept and that the following
> should be added: "Because of that, using the --ignore-space-change
> option is recommended."
> 
> Note: Earlier in the discussion, Johannes Sixt suggested -w
> (--ignore-all-space), but this is wrong, as
> 
>    git diff --word-diff -w <(printf foo) <(printf "f o o")
> 
> gives no differences while one has 1 word "foo" vs 3 words "f o o".
> 
> However, --ignore-space-change is actually not even sufficient
> since
> 
>    git diff --ignore-space-change <(printf "foo bar") <(printf "foo\nbar")
> 
> finds differences though there are only space changes (thus this
> may affect hunks in case --word-diff would be used too). However,
> I suppose that the cases where --word-diff --ignore-space-change
> would not give a "real word diff" would be quite rare in practice.

I'm a bit wary of recommending -w unconditionally in case it gives 
unexpected results. I've not really found there to be a problem using 
--word-diff when reviewing code patches. In the examples you gave we'd 
ideally fix the problem by computing a single word-diff per hunk from 
the line based diff rather than splitting the hunk at each context line. 
I think we'd probably want to exclude the leading and trailing context 
to keep the hunk header accurate but we'd get better results by 
calculating the word diff of everything in the hunk between the first 
changed line and the last changed line.

Thanks

Phillip