From: Julia Evans <julia@jvns.ca>

The top piece of feedback users always give about man pages is always
that they want better examples that are relevant to them.

The EXAMPLES section's structure has remained mostly unchanged since
2007, which was before we knew how people were going to use `git diff`.
Update it with ways of using `git diff` that are popular with Git
users, gathered by asking Mastodon users for their most commonly used
incantations. Keep the example that was added since 2007
(`git diff AUTO_MERGE`), rewording it to use the more familiar term
"merge conflict" instead of "textual conflict".

Add a note about the EXAMPLES section in the DESCRIPTION since otherwise
readers are unlikely to know it's there. `git diff` is a command where
it's more important than usual to have examples because the command has
so many different forms.

Some design choices:

- Mention both `git diff --staged` and `git diff --cached`, because
  "staged" is the term the Git user interface uses and several users
  said they find it easier to understand. Add an entry for --staged
  saying that it's a synonym. Like with `git switch`, and `git checkout`
  it's useful to leave the older version for folks who are used to using
  `git diff --cached` since we've seen that many people who are used to
  using a command don't see any value in changing how they use it.
- Use a definition list for the examples instead of the footnote style,
  so that the description and the example are right next to each other
  and it's easier to read.
- Use `--merge-base` instead of `...` since several users said they
  find .. vs ... confusing. It's much more obvious what --merge-base
  does.
- Link the options in the examples to make them faster to look up
- Use sub-subsection headings for the different parts to make
  them more visually distinct and easy to scan.

Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
Signed-off-by: Julia Evans <julia@jvns.ca>

Submitted-As: https://lore.kernel.org/git/pull.2293.v2.git.1793893217889.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2293.git.1793720007182.gitgitgadget@gmail.com