Re: [PATCH] doc: git-diff: rewrite EXAMPLES section

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 3, 2026, 19:44 UTC
Message-ID: <xmqqbj857l9r.fsf@gitster.g>
In-Reply-To: <pull.2293.git.1793720007182.gitgitgadget@gmail.com>

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

Show 11 quoted lines

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

Show 24 quoted lines

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