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

[Junio C Hamano <gitster@pobox.com>]

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