Julia Evans's patch rewrites the EXAMPLES section of git-diff. She says users consistently ask for better examples, that the section's structure has barely changed since 2007, and that she gathered popular invocations by asking Mastodon users. The patch also adds a note in DESCRIPTION pointing to the examples, because readers are unlikely to find them otherwise and git diff has so many forms.
Junio Hamano's first response was that patches are sent to the list to invite comment. In the later discussion, Evans said it is hard to learn from history why examples added 20 years ago exist, since commit messages from then are terse. She said she dropped the git diff AUTO_MERGE example because she wanted to start with commands people said they found useful, but would restore it.
Hamano's main objection was to switching an example from --cached to --staged in isolation. He said he considers the change mostly churn and does not support it, but would not veto it. His problem was consistency: the SYNOPSIS never mentions --staged, and the --cached documentation explains it as a synonym, so a lone example using --staged looks odd. If --staged were to be promoted, he said, matching changes to the main text would be needed. Evans replied that several people find --cached confusing and that --staged matches the language Git uses elsewhere, but that she can change it back.
Hamano also said he would not want to see line-wrapped sentences in tables, because that makes cut-and-paste impossible, while acknowledging that preferences vary. He said the --staged change should not be sneaked into an unrelated change that converts the format to a table. Evans then said she had learned that AsciiDoc supports horizontal definition lists, which she thinks suit this better than a table. They can be turned into vertical lists by removing [horizontal] if needed. The thread ends with the patch reposted, and no maintainer verdict on the new layout is in the excerpts.