From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 03 Nov 2026 19:44:16 GMT
Subject: Re: [PATCH] doc: git-diff: rewrite EXAMPLES section
Message-ID: <xmqqbj857l9r.fsf@gitster.g>
In-Reply-To: <pull.2293.git.1793720007182.gitgitgadget@gmail.com>

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