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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 3, 2026, 20:33 UTC
Message-ID: <xmqqtslx64em.fsf@gitster.g>
In-Reply-To: <9a6ae876-78d5-4513-8c75-c4c071c3db6a@app.fastmail.com>

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

Show 8 quoted lines

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

Show 6 quoted lines

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