[jvns]

changes in v2:

• Switch from tables to a definition list, to avoid wrapping but still staying relatively compact.
• Mention git diff --cached alongside git diff --staged so folks can use whichever version they prefer, and update the commit message with some notes about that. It's an example of one of many situations in Git where what's best to recommend for new users and what's best for long-term users is not necessarily the same.
• Put back AUTO_MERGE (thanks to Junio for pointing out that it was added much more recently than all the rest of the examples)

changes in v3:

• Remove the changes to --cached/--staged in the SYNOPSIS and DESCRIPTION.
• Squash the formatting changes from Junio for the links.

cc: "D. Ben Knoble" ben.knoble@gmail.com
cc: Tuomas Ahola taahol@utu.fi
cc: Jeff King peff@peff.net
cc: Kaartic Sivaraam kaartic.sivaraam@gmail.com

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2293.git.1793720007182.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2293/jvns/diff-v1

To fetch this version to local tag pr-2293/jvns/diff-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2293/jvns/diff-v1

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

>      * I'm not 100% sure about the table format, it does make it more
>        compact which is really nice and makes it much more readable, but on
>        an 80-character terminal there is some wrapping. One potential con is
>        that it means we can't include as many details about what the command
>        does. From my point of view that's a good thing because in a "cheat
>        sheet" format it's very important to be concise, and people can
>        always read the rest of the man page for the details.

While working on something else immediately after sending this,
I learned that Asciidoc has support for horizontal definition lists
which I think would make more sense than a table here.
And they can be easily changed to a vertical definition list by
just removing the [horizontal] if there's an issue in the future.
https://docs.asciidoctor.org/asciidoc/latest/lists/horizontal/ 

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>     Here's what one of the tables looks like on an 80-character terminal
>     with a little bit of wrapping.
>     
>        ┌─────────────────────────┬───────────────────────┐
>        │Ignore all whitespace    │ git diff              │
>        │changes                  │ --ignore-all-space    │
>        ├─────────────────────────┼───────────────────────┤
>        │Show which individual    │ git diff --word-diff  │
>        │words changed instead of │                       │
>        │the whole line           │                       │
>        └─────────────────────────┴───────────────────────┘

Personally, I would not want to see these line-wrapped sentences in
tables, which makes it impossible to cut-and-paste.  But preferences
vary from person to person, of course, on these things.

> -Various ways to check your working tree::
> -+
> -------------
> -$ git diff            <1>
> -$ git diff --cached   <2>
> -$ git diff HEAD       <3>
> -$ git diff AUTO_MERGE <4>
> -------------
> -+
> -<1> Changes in the working tree not yet staged for the next commit.
> -<2> Changes between the index and your last commit; what you
> -    would be committing if you run `git commit` without `-a` option.
> -<3> Changes in the working tree since your last commit; what you
> -    would be committing if you run `git commit -a`
> -<4> Changes in the working tree you've made to resolve textual
> -    conflicts so far.
> ...
> +[cols="1,1"]
> +|===
> +|Show unstaged changes
> +|`git diff`
> +
> +|Show staged changes
> +|`git diff --staged`

Do not sneak this change into an unrelated "change the format to use
table to make it readable" topic.  Doing this change to just this
single example would be a severe regression.

Look at SYNOPSIS of "git help diff" and notice there is no mention
of "--staged".  The description on "--cached" explains it as a
synonym for it.  If we wanted to promote "--staged" (which I would
not personally support), we'd need to do matching changes to the
main part of the text.

> +|Show all changes since the latest commit
> +|`git diff HEAD`
> +|===

Yes, as you mentioned in the commentary, loss of AUTO_MERGE is a
regression.  I do not see a reason why you needed to drop it?  Is it
because some external limitation like you cannot have a table with
more than 3 rows or something?

Thanks.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

>> +[cols="1,1"]
>> +|===
>> +|Show unstaged changes
>> +|`git diff`
>> +
>> +|Show staged changes
>> +|`git diff --staged`
>
> Do not sneak this change into an unrelated "change the format to use
> table to make it readable" topic.  Doing this change to just this
> single example would be a severe regression.

I can change it back, I didn't realize it would be an issue.

I changed it because several people said that they find `--cached`
confusing and that `--staged` was easier to understand because
that's the language Git normally uses in its UI when talking about
staged changes.

> Look at SYNOPSIS of "git help diff" and notice there is no mention
> of "--staged".  The description on "--cached" explains it as a
> synonym for it.  If we wanted to promote "--staged" (which I would
> not personally support), we'd need to do matching changes to the
> main part of the text.
>
>> +|Show all changes since the latest commit
>> +|`git diff HEAD`
>> +|===
>
> Yes, as you mentioned in the commentary, loss of AUTO_MERGE is a
> regression.  I do not see a reason why you needed to drop it?  Is it
> because some external limitation like you cannot have a table with
> more than 3 rows or something?

I dropped it because I wanted to start with just the commands that
people said they found useful, and it can be hard to introduce
too many "new" commands that aren't well-known already.

That said I think `git diff AUTO_MERGE` seems useful and I'm happy
to put it back.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans" <julia@jvns.ca> writes:

>>> +|Show staged changes
>>> +|`git diff --staged`
>>
>> Do not sneak this change into an unrelated "change the format to use
>> table to make it readable" topic.  Doing this change to just this
>> single example would be a severe regression.
>
> I can change it back, I didn't realize it would be an issue.

Changing this example alone without checking its fit in the wider
context is what made it problematic.  I do not personally support
"cached to staged" because I consider it mostly a meaningless
churn, but that is different from saying I will veto it.

I just wanted to see a bit more consistency; without changing the
main text, the change to the example made it look like a very odd
thing to have there.  You see the option named "--staged" but it
is explained nowhere other than being a synonym to another option
that is much more widely explained.

> I dropped it because I wanted to start with just the commands that
> people said they found useful, and it can be hard to introduce
> too many "new" commands that aren't well-known already.
>
> That said I think `git diff AUTO_MERGE` seems useful and I'm happy
> to put it back.

FWIW, what is in the current document was added by choosing what
were found useful.  So you would want to think twice (note: this
is very different from "do not change") before removing existing
ones or replacing them with something else.  After spending a
significant amount of effort on these documentation updates you are
making, if a new person came and rewrote them again without
understanding or paying much attention to your reasoning behind how
you arrived at your version, I would imagine that you would feel
terrible.  Please give the last person who wrote these documents
the same courtesy and respect.

Thanks.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

On Tue, Nov 3, 2026, at 3:33 PM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>>>> +|Show staged changes
>>>> +|`git diff --staged`
>>>
>>> Do not sneak this change into an unrelated "change the format to use
>>> table to make it readable" topic.  Doing this change to just this
>>> single example would be a severe regression.
>>
>> I can change it back, I didn't realize it would be an issue.
>
> Changing this example alone without checking its fit in the wider
> context is what made it problematic.  I do not personally support
> "cached to staged" because I consider it mostly a meaningless
> churn, but that is different from saying I will veto it.
>
> I just wanted to see a bit more consistency; without changing the
> main text, the change to the example made it look like a very odd
> thing to have there.  You see the option named "--staged" but it
> is explained nowhere other than being a synonym to another option
> that is much more widely explained.
>
>> I dropped it because I wanted to start with just the commands that
>> people said they found useful, and it can be hard to introduce
>> too many "new" commands that aren't well-known already.
>>
>> That said I think `git diff AUTO_MERGE` seems useful and I'm happy
>> to put it back.
>
> FWIW, what is in the current document was added by choosing what
> were found useful.  So you would want to think twice (note: this
> is very different from "do not change") before removing existing
> ones or replacing them with something else.  After spending a
> significant amount of effort on these documentation updates you are
> making, if a new person came and rewrote them again without
> understanding or paying much attention to your reasoning behind how
> you arrived at your version, I would imagine that you would feel
> terrible.  Please give the last person who wrote these documents
> the same courtesy and respect.

It's very hard to understand from the Git history the reasons for
adding examples that were added 20 years ago, for example
in 803f498c03b where these were added, especially since the commit
messages from 20 years ago tend to be a lot more terse.

+Limiting the diff output::
++
+------------
+$ git diff --diff-filter=MRC <1>
+$ git diff --name-status -r <2>
+$ git diff arch/i386 include/asm-i386 <3>

I do hear that AUTO_MERGE was added more recently.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans" <julia@jvns.ca> writes:

> It's very hard to understand from the Git history the reasons for
> adding examples that were added 20 years ago, for example
> in 803f498c03b where these were added, especially since the commit
> messages from 20 years ago tend to be a lot more terse.

Sure.  But that is why you send patches here to invite people to
comment on.

> I do hear that AUTO_MERGE was added more recently.

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2293.v2.git.1793893217889.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2293/jvns/diff-v2

To fetch this version to local tag pr-2293/jvns/diff-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2293/jvns/diff-v2

[taahol]

Hmm, it seems git diff -h and git diff --help are out of sync:

$ make test T=t0450-txt-doc-vs-help.sh GIT_TEST_OPTS="-v --run=-218"

expecting success of 0450.218 'diff -h output and SYNOPSIS agree': 
                t2s="$(adoc_to_synopsis "$builtin")" &&                                              
                if test "$builtin" = "merge-tree"                                                    
                then                                                                                 
                        test_when_finished "rm -f t2s.new" &&                                        
                        sed -e 's/ (deprecated)$//g' <"$t2s" >t2s.new                                
                        t2s=t2s.new                                                                  
                fi &&                                                                                
                h2s="$(help_to_synopsis "$builtin")" &&                                              
                                                                                                     
                # The *.adoc and -h use different spacing for the                                    
                # alignment of continued usage output, normalize it.                                 
                align_after_nl "$builtin" <"$t2s" >adoc &&                                           
                align_after_nl "$builtin" <"$h2s" >help &&                                           
                test_cmp adoc help                                                                   
                                                                                                     
--- adoc        2026-11-05 17:03:30.605557385 +0000
+++ help        2026-11-05 17:03:30.605557385 +0000
@@ -1,5 +1,5 @@
 git diff [<options>] [<commit>] [--] [<path>...]
-git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
+git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
 git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
 git diff [<options>] <commit>...<commit> [--] [<path>...]
 git diff [<options>] <blob> <blob>
not ok 218 - diff -h output and SYNOPSIS agree
#
#                       t2s="$(adoc_to_synopsis "$builtin")" &&
#                       if test "$builtin" = "merge-tree"
#                       then
#                               test_when_finished "rm -f t2s.new" &&
#                               sed -e 's/ (deprecated)$//g' <"$t2s" >t2s.new
#                               t2s=t2s.new
#                       fi &&
#                       h2s="$(help_to_synopsis "$builtin")" &&
#
#                       # The *.adoc and -h use different spacing for the
#                       # alignment of continued usage output, normalize it.
#                       align_after_nl "$builtin" <"$t2s" >adoc &&
#                       align_after_nl "$builtin" <"$h2s" >help &&
#                       test_cmp adoc help
#

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>      +-git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>      ++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]

This goes against what you said earlier, which was

> - Mention both `git diff --staged` and `git diff --cached`, because
>   "staged" is the term the Git user interface uses and several users
>   said they find it easier to understand. Add an entry for --staged
>   saying that it's a synonym. Like with `git switch`, and `git checkout`
>   it's useful to leave the older version for folks who are used to using
>   `git diff --cached` since we've seen that many people who are used to
>   using a command don't see any value in changing how they use it.

Perhaps (--cached|--staged) or have two lines (i.e., turn the range
diff into

>      + git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>      ++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]

or something).

>      +@@ Documentation/git-diff.adoc: files on disk.
>      + 	do not give _<commit>_, it defaults to `HEAD`.
>      + 	If `HEAD` does not exist (e.g. unborn branches) and
>      + 	_<commit>_ is not given, it shows all staged changes.
>      +-	`--staged` is a synonym of `--cached`.
>      ++	`--cached` is a synonym of `--staged`.

And this is the other way around.

Other than that, the rest, including the resurrection of AUTO_MERGE,
looked OK.

[gitgitgadget]

Tuomas Ahola wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> wrote:

>  --------
>  [synopsis]
>  git diff [<options>] [<commit>] [--] [<path>...]
> -git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
> +git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
>  git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
>  git diff [<options>] <commit>...<commit> [--] [<path>...]
>  git diff [<options>] <blob> <blob>

Sorry, that breaks the test number 0450.218.  Please change the synopsis of
"git diff -h" as well.

[gitgitgadget]

User Tuomas Ahola <taahol@utu.fi> has been added to the cc: list.

[gitgitgadget]

This branch is now known as je/doc-git-diff-examples.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Junio C Hamano <gitster@pobox.com> writes:

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>      +-git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>>      ++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
>
> This goes against what you said earlier, which was
>
>> - Mention both `git diff --staged` and `git diff --cached`, because
>>   "staged" is the term the Git user interface uses and several users
>>   said they find it easier to understand. Add an entry for --staged
>>   saying that it's a synonym. Like with `git switch`, and `git checkout`
>>   it's useful to leave the older version for folks who are used to using
>>   `git diff --cached` since we've seen that many people who are used to
>>   using a command don't see any value in changing how they use it.
>
> Perhaps (--cached|--staged) or have two lines (i.e., turn the range
> diff into
>
>>      + git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>>      ++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
>
> or something).

Clarification.

The point is that there is a difference between giving wider
exposure to "--staged" as an accepted synonym and swapping offical
option with the synonym, let alone deprecating "--cached".

You may have heard from several users that they like the word
"staged", but I am sure there are more than several thousand users
who have been using Git since before the synonym was introduced.

>>      +@@ Documentation/git-diff.adoc: files on disk.
>>      + 	do not give _<commit>_, it defaults to `HEAD`.
>>      + 	If `HEAD` does not exist (e.g. unborn branches) and
>>      + 	_<commit>_ is not given, it shows all staged changes.
>>      +-	`--staged` is a synonym of `--cached`.
>>      ++	`--cached` is a synonym of `--staged`.
>
> And this is the other way around.
>
> Other than that, the rest, including the resurrection of AUTO_MERGE,
> looked OK.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Tuomas Ahola <taahol@utu.fi> writes:

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> wrote:
>
>>  --------
>>  [synopsis]
>>  git diff [<options>] [<commit>] [--] [<path>...]
>> -git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>> +git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
>>  git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
>>  git diff [<options>] <commit>...<commit> [--] [<path>...]
>>  git diff [<options>] <blob> <blob>
>
> Sorry, that breaks the test number 0450.218.  Please change the synopsis of
> "git diff -h" as well.

Ah, good point.  Thanks for noticing.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> The top piece of feedback users always give about man pages is always
> that they want better examples that are relevant to them.

I'll add this squashable fix-up on top before queuing; the change to
the code is because otherwise this change would break a test.

Thanks.


 Documentation/git-diff.adoc | 8 ++++----
 builtin/diff.c              | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git c/Documentation/git-diff.adoc w/Documentation/git-diff.adoc
index f15e56633e..42360f9b5e 100644
--- c/Documentation/git-diff.adoc
+++ w/Documentation/git-diff.adoc
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [synopsis]
 git diff [<options>] [<commit>] [--] [<path>...]
-git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
+git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]
 git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
 git diff [<options>] <commit>...<commit> [--] [<path>...]
 git diff [<options>] <blob> <blob>
@@ -47,7 +47,7 @@ to diff.
 	difference. All such pathspecs must be relative as they
 	apply to both sides of the diff.
 
-`git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]`::
+`git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]`::
 
 	This form is to view the changes you staged for the next
 	commit relative to the named _<commit>_.  Typically you
@@ -55,10 +55,10 @@ to diff.
 	do not give _<commit>_, it defaults to `HEAD`.
 	If `HEAD` does not exist (e.g. unborn branches) and
 	_<commit>_ is not given, it shows all staged changes.
-	`--cached` is a synonym of `--staged`.
+	`--staged` is a synonym of `--cached`.
 +
 If `--merge-base` is given, instead of using _<commit>_, use the merge base
-of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to
+of _<commit>_ and `HEAD`.  `git diff --staged --merge-base A` is equivalent to
 `git diff --staged $(git merge-base A HEAD)`.
 
 `git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::
diff --git c/builtin/diff.c w/builtin/diff.c
index 18b1083e98..13fe8a21e0 100644
--- c/builtin/diff.c
+++ w/builtin/diff.c
@@ -31,7 +31,7 @@
 
 static const char builtin_diff_usage[] =
 "git diff [<options>] [<commit>] [--] [<path>...]\n"
-"   or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n"
+"   or: git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]\n"
 "   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
 "   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\n"
 "   or: git diff [<options>] <blob> <blob>\n"

[gitgitgadget]

This patch series was integrated into seen via git@d202601.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch je/doc-git-diff-examples on the Git mailing list:

The EXAMPLES section of the 'git diff' manual page has been  rewritten
to use a more readable cheat-sheet format, incorporating  commonly
used examples while preserving historical examples.

Waiting for response.
cf. <xmqqse1fuoof.fsf@gitster.g>
cf. <xmqq33tft62l.fsf@gitster.g>
source: <pull.2293.v2.git.1793893217889.gitgitgadget@gmail.com>

[gitgitgadget]

Jeff King wrote on the Git mailing list (how to reply to this email):

On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:

> +[[name_only]]
>  `--name-only`::
>  	Show only the name of each changed file in the post-image tree.
>  	The file names are often encoded in UTF-8.
>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>  	manual page.

Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
latter doesn't create the anchors, and then xmlto complaints that the
result doesn't validate.

Doing it like this works in both:

  `--name-only`[[name_only]]::
	...

but...yikes. It's pretty ugly. This of course tempts me in the direction
of ditching python asciidoc support, but I'm not sure if you want to
hold up your series for that.

> @@ -417,6 +420,7 @@ endif::git-diff[]
>  	Ignore changes in amount of whitespace.  This ignores whitespace
>  	at line end, and considers all other sequences of one or
>  	more whitespace characters to be equivalent.
> +[[ignore_all_space]]
>  `ignore-all-space`::
>  	Ignore whitespace when comparing lines. This ignores differences
>  	even if one line has whitespace where the other line has none.

This one is describing the ignore-all-space option of --color-moved-ws.
Did you mean to put it alongside -w / --ignore-all-space?

-Peff

[gitgitgadget]

User Jeff King <peff@peff.net> has been added to the cc: list.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Jeff King <peff@peff.net> writes:

> On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
>
>> +[[name_only]]
>>  `--name-only`::
>>  	Show only the name of each changed file in the post-image tree.
>>  	The file names are often encoded in UTF-8.
>>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>>  	manual page.
>
> Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
> latter doesn't create the anchors, and then xmlto complaints that the
> result doesn't validate.

An offtopic tangent but didn't we repeatedly float ideas to drop
support for AsciiDoc, make sure our documentation set renders well
only with AsciiDoctor, and tell folks who do not use AsciiDoctor to
use pre-rendered documentation pages from git-htmldocs.git and
git-manpages.git repositories at https://git.kernel.org/pub/scm/git/
during the past several months?

Perhaps I should add an entry to the BreakingChanges document (well,
I know I know I do not think it belongs there, but since we hit this
so many times already .....).

[gitgitgadget]

"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email):

On Thu, Nov 5, 2026 at 1:18 PM Junio C Hamano <gitster@pobox.com> wrote:

> Clarification.
>
> The point is that there is a difference between giving wider
> exposure to "--staged" as an accepted synonym and swapping offical
> option with the synonym, let alone deprecating "--cached".
>
> You may have heard from several users that they like the word
> "staged", but I am sure there are more than several thousand users
> who have been using Git since before the synonym was introduced.

For sideline readers, some of this is documented in "git help cli" in
the "NOTES ON FREQUENTLY CONFUSED OPTIONS" section.

-- 
D. Ben Knoble

[gitgitgadget]

Jeff King wrote on the Git mailing list (how to reply to this email):

On Sat, Nov 07, 2026 at 08:35:29PM -0800, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
> >
> >> +[[name_only]]
> >>  `--name-only`::
> >>  	Show only the name of each changed file in the post-image tree.
> >>  	The file names are often encoded in UTF-8.
> >>  	For more information see the discussion about encoding in the linkgit:git-log[1]
> >>  	manual page.
> >
> > Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
> > latter doesn't create the anchors, and then xmlto complaints that the
> > result doesn't validate.
> 
> An offtopic tangent but didn't we repeatedly float ideas to drop
> support for AsciiDoc, make sure our documentation set renders well
> only with AsciiDoctor, and tell folks who do not use AsciiDoctor to
> use pre-rendered documentation pages from git-htmldocs.git and
> git-manpages.git repositories at https://git.kernel.org/pub/scm/git/
> during the past several months?

Yeah, that's what I was hinting at near the bottom of my message. :)

But it's a big enough change that this series should probably just
accept the ugly syntax for now, rather than waiting for us to drop
python asciidoc support.

> Perhaps I should add an entry to the BreakingChanges document (well,
> I know I know I do not think it belongs there, but since we hit this
> so many times already .....).

I'm not sure if it actually rises to the level of BreakingChanges. It is
a build issue, not a user-facing one. And there is an easy workaround
that can be applied anywhere for platforms that can't or don't want to
use asciidoctor. So it may cause some slight hassle for packagers or
those who build themselves, but it's not really breaking anybody.

-Peff

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Jeff King <peff@peff.net> writes:

> On Sat, Nov 07, 2026 at 08:35:29PM -0800, Junio C Hamano wrote:
>
>> An offtopic tangent but didn't we repeatedly float ideas to drop
>> support for AsciiDoc, make sure our documentation set renders well
>> only with AsciiDoctor, and tell folks who do not use AsciiDoctor to
>> use pre-rendered documentation pages from git-htmldocs.git and
>> git-manpages.git repositories at https://git.kernel.org/pub/scm/git/
>> during the past several months?
>
> Yeah, that's what I was hinting at near the bottom of my message. :)
>
> But it's a big enough change that this series should probably just
> accept the ugly syntax for now, rather than waiting for us to drop
> python asciidoc support.

Yup, agreed.  Improvements for these examples do not have to be held
hostage on the toolchain support.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Jeff King <peff@peff.net> writes:

> On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
>
>> +[[name_only]]
>>  `--name-only`::
>>  	Show only the name of each changed file in the post-image tree.
>>  	The file names are often encoded in UTF-8.
>>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>>  	manual page.
>
> Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
> latter doesn't create the anchors, and then xmlto complaints that the
> result doesn't validate.
>
> Doing it like this works in both:
>
>   `--name-only`[[name_only]]::
> 	...
>
> but...yikes. It's pretty ugly. This of course tempts me in the direction
> of ditching python asciidoc support, but I'm not sure if you want to
> hold up your series for that.

In any case, I'll queue another SQUASH??? commit on top of the topic
until v3 materiazlies to fix these issues we have accumulated so
far.



diff --git c/Documentation/diff-options.adoc w/Documentation/diff-options.adoc
index 2dc54fa00e..bb46fd065b 100644
--- c/Documentation/diff-options.adoc
+++ w/Documentation/diff-options.adoc
@@ -201,8 +201,7 @@ diff" algorithm internally.
 
 include::diff-algorithm-option.adoc[]
 
-[[stat]]
-`--stat[=<width>[,<name-width>[,<count>]]]`::
+`--stat[=<width>[,<name-width>[,<count>]]]`[[stat]]::
 	Generate a diffstat. By default, as much space as necessary
 	will be used for the filename part, and the rest for the graph
 	part. Maximum width defaults to terminal width, or 80 columns
@@ -319,15 +318,13 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
-[[name_only]]
-`--name-only`::
+`--name-only`[[name_only]]::
 	Show only the name of each changed file in the post-image tree.
 	The file names are often encoded in UTF-8.
 	For more information see the discussion about encoding in the linkgit:git-log[1]
 	manual page.
 
-[[name_status]]
-`--name-status`::
+`--name-status`[[name_status]]::
 	Show only the name(s) and status of each changed file. See the description
 	of the `--diff-filter` option on what the status letters mean.
 	Just like `--name-only` the file names are often encoded in UTF-8.
@@ -420,8 +417,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
-[[ignore_all_space]]
-`ignore-all-space`::
+`ignore-all-space`[[ignore_all_space]]::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.
 `allow-indentation-change`::
@@ -436,8 +432,7 @@ endif::git-diff[]
 	used to override configuration settings. It is the same as
 	`--color-moved-ws=no`.
 
-[[word_diff]]
-`--word-diff[=<mode>]`::
+`--word-diff[=<mode>]`[[word_diff]]::
 	By default, words are delimited by whitespace; see
 	`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and
 	must be one of:

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Junio C Hamano <gitster@pobox.com> writes:

> Jeff King <peff@peff.net> writes:
>
>> On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
>>
>>> +[[name_only]]
>>>  `--name-only`::
>>>  	Show only the name of each changed file in the post-image tree.
>>>  	The file names are often encoded in UTF-8.
>>>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>>>  	manual page.
>>
>> Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
>> latter doesn't create the anchors, and then xmlto complaints that the
>> result doesn't validate.
>>
>> Doing it like this works in both:
>>
>>   `--name-only`[[name_only]]::
>> 	...
>>
>> but...yikes. It's pretty ugly. This of course tempts me in the direction
>> of ditching python asciidoc support, but I'm not sure if you want to
>> hold up your series for that.
>
> In any case, I'll queue another SQUASH??? commit on top of the topic
> until v3 materiazlies to fix these issues we have accumulated so
> far.

And I realized that we need yet another SQUASH to address "isn't it
a value of another option?"  point.

    SQUASH???
    
    it is likely that the annotation was meant to go with --dashed-option

diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index bb46fd065b..dbac3b8275 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -417,7 +417,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
-`ignore-all-space`[[ignore_all_space]]::
+`ignore-all-space`::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.
 `allow-indentation-change`::
@@ -783,7 +783,7 @@ endif::git-format-patch[]
 	more whitespace characters to be equivalent.
 
 `-w`::
-`--ignore-all-space`::
+`--ignore-all-space`[[ignore_all_space]]::
 	Ignore whitespace when comparing lines.  This ignores
 	differences even if one line has whitespace where the other
 	line has none.

[gitgitgadget]

Jeff King wrote on the Git mailing list (how to reply to this email):

On Mon, Nov 09, 2026 at 02:40:20PM -0800, Junio C Hamano wrote:

> > In any case, I'll queue another SQUASH??? commit on top of the topic
> > until v3 materiazlies to fix these issues we have accumulated so
> > far.
> 
> And I realized that we need yet another SQUASH to address "isn't it
> a value of another option?"  point.

Thanks, both of these squashes look good to me, and address all the
issues I saw.

-Peff

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

>>>      + git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
>>>      ++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
>>
>> or something).
>
> Clarification.
>
> The point is that there is a difference between giving wider
> exposure to "--staged" as an accepted synonym and swapping offical
> option with the synonym, let alone deprecating "--cached".

Sorry, that's embarrassing, I didn't mean to include this change.
I did an experimental rewrite to see what it would like to rename `--cached`
to `--staged`, decided it would be better to keep the scope small,
and I thought I'd undone it before submitting it.

Will take this out.

>>>      +@@ Documentation/git-diff.adoc: files on disk.
>>>      + 	do not give _<commit>_, it defaults to `HEAD`.
>>>      + 	If `HEAD` does not exist (e.g. unborn branches) and
>>>      + 	_<commit>_ is not given, it shows all staged changes.
>>>      +-	`--staged` is a synonym of `--cached`.
>>>      ++	`--cached` is a synonym of `--staged`.
>>
>> And this is the other way around.
>>
>> Other than that, the rest, including the resurrection of AUTO_MERGE,
>> looked OK.

Good to hear.

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

On Mon, Nov 9, 2026, at 5:40 PM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Jeff King <peff@peff.net> writes:
>>
>>> On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
>>>
>>>> +[[name_only]]
>>>>  `--name-only`::
>>>>  	Show only the name of each changed file in the post-image tree.
>>>>  	The file names are often encoded in UTF-8.
>>>>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>>>>  	manual page.
>>>
>>> Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
>>> latter doesn't create the anchors, and then xmlto complaints that the
>>> result doesn't validate.
>>>
>>> Doing it like this works in both:
>>>
>>>   `--name-only`[[name_only]]::
>>> 	...
>>>
>>> but...yikes. It's pretty ugly. This of course tempts me in the direction
>>> of ditching python asciidoc support, but I'm not sure if you want to
>>> hold up your series for that.
>>
>> In any case, I'll queue another SQUASH??? commit on top of the topic
>> until v3 materiazlies to fix these issues we have accumulated so
>> far.

Thanks for this, I don't know how to apply a patch from an email but
I'll ask in the Discord to try to learn how. Same for the other changes.

[gitgitgadget]

Kaartic Sivaraam wrote on the Git mailing list (how to reply to this email):

On 11/10/26 19:16, Julia Evans wrote:
> 
> On Mon, Nov 9, 2026, at 5:40 PM, Junio C Hamano wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>>
>>> In any case, I'll queue another SQUASH??? commit on top of the topic
>>> until v3 materiazlies to fix these issues we have accumulated so
>>> far.
> 
> Thanks for this, I don't know how to apply a patch from an email but
> I'll ask in the Discord to try to learn how. Same for the other changes.

As mentioned in Discord, when Junio mentions something along the lines of "I'll queue another SQUASH??? commit" , it means he would've already queued the SQUASH commit in the topic branch in his tree. You can view the same using something like:

  $ git remote add jch https://github.com/gitster/git
  $ git fetch jch je/doc-git-diff-examples
  $ git log FETCH_HEAD

Then on your local topic branch, you can do:

  $ git cherry-pick --no-commit <List_of_SQUASH_commit_ID...>

Hope this helps.

-- 
Sivaraam

[gitgitgadget]

User Kaartic Sivaraam <kaartic.sivaraam@gmail.com> has been added to the cc: list.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Julia Evans" <julia@jvns.ca> writes:

> Thanks for this, I don't know how to apply a patch from an email but
> I'll ask in the Discord to try to learn how. Same for the other changes.

It might be easier to fetch from me, find these squash commits from
'seen' ("git log seen" is your friend), and cherry pick them on top
of what you have.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch je/doc-git-diff-examples on the Git mailing list:

The EXAMPLES section of the 'git diff' manual page has been  rewritten
to use a more readable cheat-sheet format, incorporating  commonly
used examples while preserving historical examples.

Waiting for response.
cf. <xmqqse1fuoof.fsf@gitster.g>
cf. <xmqq33tft62l.fsf@gitster.g>
cf. <20261108023730.GA1242909@coredump.intra.peff.net>
source: <pull.2293.v2.git.1793893217889.gitgitgadget@gmail.com>

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2293.v3.git.1794427993457.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2293/jvns/diff-v3

To fetch this version to local tag pr-2293/jvns/diff-v3:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2293/jvns/diff-v3

[gitgitgadget]

This patch series is no longer integrated into seen.