From: Julia Evans Date: Tue, 03 Nov 2026 19:52:16 GMT Subject: Re: [PATCH] doc: git-diff: rewrite EXAMPLES section Message-ID: <9a6ae876-78d5-4513-8c75-c4c071c3db6a@app.fastmail.com> In-Reply-To: >> +[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. > 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.