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

From: Julia Evans <julia@jvns.ca>
Date: Nov 3, 2026, 19:52 UTC
Message-ID: <9a6ae876-78d5-4513-8c75-c4c071c3db6a@app.fastmail.com>
In-Reply-To: <xmqqbj857l9r.fsf@gitster.g>

Show 11 quoted lines

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

Show 14 quoted lines

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