From: Julia Evans Date: Tue, 03 Nov 2026 20:45:22 GMT Subject: Re: [PATCH] doc: git-diff: rewrite EXAMPLES section Message-ID: In-Reply-To: On Tue, Nov 3, 2026, at 3:33 PM, Junio C Hamano wrote: > "Julia Evans" 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. It's very hard to understand from the Git history the reasons for adding examples that were added 20 years ago, for example in 803f498c03b where these were added, especially since the commit messages from 20 years ago tend to be a lot more terse. +Limiting the diff output:: ++ +------------ +$ git diff --diff-filter=MRC <1> +$ git diff --name-status -r <2> +$ git diff arch/i386 include/asm-i386 <3> I do hear that AUTO_MERGE was added more recently.