doc: git-diff: rewrite EXAMPLES section

From: Julia Evans <[email protected]>

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.

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:

- Use --merge-base instead of ... since several users said they find .. vs ... confusing. It's much more obvious what --merge-base does.
- Use a table format instead of the footnote-style formatting since the footnote style is quite difficult to follow. It's easier to follow if the description is right next to the command it's describing.
- 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.

---
doc: git-diff: rewrite EXAMPLES section

A couple of self-review comments:

* May want to add back the git diff AUTO_MERGE, nobody mentioned it but it's often nice to include 1 cool little-known example to try to promote it.
* I'm not 100% sure about the table format, it does make it more compact which is really nice and makes it much more readable, but on an 80-character terminal there is some wrapping. One potential con is that it means we can't include as many details about what the command does. From my point of view that's a good thing because in a "cheat sheet" format it's very important to be concise, and people can always read the rest of the man page for the details.

Here's what one of the tables looks like on an 80-character terminal with a little bit of wrapping.

┌─────────────────────────┬───────────────────────┐
│Ignore all whitespace │ git diff │
│changes │ --ignore-all-space │
├─────────────────────────┼───────────────────────┤
│Show which individual │ git diff --word-diff │
│words changed instead of │ │
│the whole line │ │
└─────────────────────────┴───────────────────────┘

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2293%2Fjvns%2Fdiff-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2293/jvns/diff-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2293

 Documentation/diff-options.adoc |   5 ++
 Documentation/git-diff.adoc     | 149 ++++++++++++++++++--------------
 2 files changed, 87 insertions(+), 67 deletions(-)

index e605d28678..2dc54fa00e 100644
@@ -201,6 +201,7 @@ diff" algorithm internally.
 
 include::diff-algorithm-option.adoc[]
 
+[[stat]]
 `--stat[=<width>[,<name-width>[,<count>]]]`::
 	Generate a diffstat. By default, as much space as necessary
 	will be used for the filename part, and the rest for the graph

@@ -318,12 +319,14 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
+[[name_only]]
 `--name-only`::
 	Show only the name of each changed file in the post-image tree.
 	The file names are often encoded in UTF-8.
 	For more information see the discussion about encoding in the linkgit:git-log[1]
 	manual page.
 
+[[name_status]]
 `--name-status`::
 	Show only the name(s) and status of each changed file. See the description
 	of the `--diff-filter` option on what the status letters mean.

@@ -417,6 +420,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
+[[ignore_all_space]]
 `ignore-all-space`::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.

@@ -432,6 +436,7 @@ endif::git-diff[]
 	used to override configuration settings. It is the same as
 	`--color-moved-ws=no`.
 
+[[word_diff]]
 `--word-diff[=<mode>]`::
 	By default, words are delimited by whitespace; see
 	`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and

base-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e

gitgitgadget

While working on something else immediately after sending this, I learned that Asciidoc has support for horizontal definition lists which I think would make more sense than a table here. And they can be easily changed to a vertical definition list by just removing the [horizontal] if there's an issue in the future.
https://docs.asciidoctor.org/asciidoc/latest/lists/horizontal/

Personally, I would not want to see these line-wrapped sentences in tables, which makes it impossible to cut-and-paste. But preferences vary from person to person, of course, on these things.

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?

Thanks.

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.

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.

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.

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.

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.

Sure. But that is why you send patches here to invite people to comment on.

From: Julia Evans <[email protected]>

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.

---
doc: git-diff: rewrite EXAMPLES section

changes in v2:

* Switch from tables to a definition list, to avoid wrapping but still staying relatively compact.
* Mention git diff --cached alongside git diff --staged so folks can use whichever version they prefer, and update the commit message with some notes about that. It's an example of one of many situations in Git where what's best to recommend for new users and what's best for long-term users is not necessarily the same.
* Put back AUTO_MERGE (thanks to Junio for pointing out that it was added much more recently than all the rest of the examples)

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2293%2Fjvns%2Fdiff-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2293/jvns/diff-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2293

Range-diff vs v1:

1: 46728e7b7a ! 1: ec565ce334 doc: git-diff: rewrite EXAMPLES section
@@ Commit message
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.
+ 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
@@ Commit message

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.
- - Use a table format instead of the footnote-style formatting since the
- footnote style is quite difficult to follow. It's easier to follow
- if the description is right next to the command it's describing.
- 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.
@@ Documentation/diff-options.adoc: endif::git-diff[]
--word-diff-regex below. The _<mode>_ defaults to plain, and

## Documentation/git-diff.adoc ##
+@@ Documentation/git-diff.adoc: SYNOPSIS
+ --------
+ [synopsis]
+ git diff [<options>] [<commit>] [--] [<path>...]
+-git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
+ git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
+ git diff [<options>] <commit>...<commit> [--] [<path>...]
+ git diff [<options>] <blob> <blob>
@@ Documentation/git-diff.adoc: between the index and a tree, changes between two trees, changes resulting
from a merge, changes between two blob objects, or changes between two
files on disk.
@@ Documentation/git-diff.adoc: between the index and a tree, changes between two t
git diff [<options>] [--] [<path>...]::

This form is to view the changes you made relative to
+@@ Documentation/git-diff.adoc: files on disk.
+ difference. All such pathspecs must be relative as they
+ apply to both sides of the diff.
+
+-git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::
++git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]::
+
+ This form is to view the changes you staged for the next
+ commit relative to the named _<commit>_. Typically you
+@@ Documentation/git-diff.adoc: files on disk.
+ do not give _<commit>_, it defaults to HEAD.
+ If HEAD does not exist (e.g. unborn branches) and
+ _<commit>_ is not given, it shows all staged changes.
+- --staged is a synonym of --cached.
++ --cached is a synonym of --staged.
+ +
+ If --merge-base is given, instead of using _<commit>_, use the merge base
+ of _<commit>_ and HEAD. git diff --cached --merge-base A is equivalent to +-git diff --cached $(git merge-base A HEAD).
++git diff --staged $(git merge-base A HEAD).
+
+ git diff [<options>] [--merge-base] <commit> [--] [<path>...]::
+
@@ Documentation/git-diff.adoc: section "3-Way Merge" for detailed information.

include::diff-format.adoc[]
@@ Documentation/git-diff.adoc: section "3-Way Merge" for detailed information.
- branch was started off it.
+Diff uncommitted changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+-Limiting the diff output::
+-+
+-------------
+-$ git diff --diff-filter=MRC <1>
+-$ git diff --name-status <2>
+-$ git diff arch/i386 include/asm-i386 <3>
+-------------
+-+
+-<1> Show only modification, rename, and copy, but not addition
+- or deletion.
+-<2> Show only names and the nature of change, but not actual
+- diff output.
+-<3> Limit diff output to named subtrees.
++Show unstaged changes::
++git diff
+
+-Munging the diff output::
+-+
+-------------
+-$ git diff --find-copies-harder -B -C <1>
+-$ git diff -R <2>
+-------------
+-+
+-<1> Spend extra cycles to find renames, copies and complete
+- rewrites (very expensive).
+-<2> Output diff in reverse.
++Show staged changes::
++git diff --staged or git diff --cached
+
-+git diff will show the files from the "before" column as deleted and -+from the "after" column as added.
-+
-+[cols="1,1"]
-+|===
-+|Show unstaged changes
-+|git diff
-+
-+|Show staged changes
-+|git diff --staged
++Show all changes since the latest commit::
++git diff HEAD
+
-+|Show all changes since the latest commit
-+|git diff HEAD
-+|===
++Show changes made to resolve a merge conflict::
++git diff AUTO_MERGE
+
+Diff a specific file/directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ Documentation/git-diff.adoc: section "3-Way Merge" for detailed information.
+diff to that file/directory. You don't always need to put a --, but it +makes it unambiguous.
+
-+[cols="1,1"]
-+|===
-+|Show how file.txt has changed since main
-+|git diff main -- file.txt
++Show how file.txt has changed since main::
++git diff main -- file.txt
+
-+|Show unstaged changes for file.txt
-+|git diff -- file.txt
++Show unstaged changes for file.txt::
++git diff -- file.txt
+
-+|Show unstaged changes in dir/
-+|git diff -- ./dir
-+|===
++Show unstaged changes in dir/::
++git diff -- ./dir
+
+Diff branches or commits
+~~~~~~~~~~~~~~~~~~~~~~~~
+
-+[cols="1,1"]
-+|===
-+|Show changes on the topic branch since it branched off main -+|git diff --merge-base main topic
++Show changes on the topic branch since it branched off main::
++git diff --merge-base main topic
+
-+|Show changes between the topic branch and the main branch -+|git diff main topic
++Show changes between the topic branch and the main branch::
++git diff main topic
+
-+|Show changes between commit ff11cc and HEAD
-+|git diff ff11cc HEAD
-+|===
++Show changes between commit ff11cc and HEAD::
++git diff ff11cc HEAD
+
+Options to summarize the output
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
-+[cols="1,1"]
-+|===
-+|Show how many lines in each file were changed
-+|git diff <<stat,--stat>>
++Show how many lines in each file were changed::
++git diff <<stat,--stat>>
+
-+|Only show names of changed files
-+|git diff <<name_only,--name-only>>
++Only show names of changed files::
++git diff <<name_only,--name-only>>
+
-+|Only show filenames and whether they were modified/deleted/added -+|git diff <<name_status,--name-status>>
-+|===
++Only show filenames and whether they were modified/deleted/added::
++git diff <<name_status,--name-status>>
+
+Options to display the diff in another way
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
-+[cols="1,1"]
-+|===
-+|Ignore all whitespace changes
-+|git diff <<ignore_all_space,--ignore-all-space>>
++Ignore all whitespace changes::
++git diff <<ignore_all_space,--ignore-all-space>>
+
-+|Show which individual words changed instead of the whole line -+|git diff <<word_diff,--word-diff>>
-+|===
-
--Limiting the diff output::
--+
--------------
--$ git diff --diff-filter=MRC <1>
--$ git diff --name-status <2>
--$ git diff arch/i386 include/asm-i386 <3>
--------------
--+
--<1> Show only modification, rename, and copy, but not addition
-- or deletion.
--<2> Show only names and the nature of change, but not actual
-- diff output.
--<3> Limit diff output to named subtrees.
-
--Munging the diff output::
--+
--------------
--$ git diff --find-copies-harder -B -C <1>
--$ git diff -R <2>
--------------
--+
--<1> Spend extra cycles to find renames, copies and complete
-- rewrites (very expensive).
--<2> Output diff in reverse.
++Show which individual words changed instead of the whole line::
++git diff <<word_diff,--word-diff>>

CONFIGURATION
-------------

 Documentation/diff-options.adoc |   5 ++
 Documentation/git-diff.adoc     | 140 ++++++++++++++++----------------
 2 files changed, 74 insertions(+), 71 deletions(-)

index e605d28678..2dc54fa00e 100644
@@ -201,6 +201,7 @@ diff" algorithm internally.
 
 include::diff-algorithm-option.adoc[]
 
+[[stat]]
 `--stat[=<width>[,<name-width>[,<count>]]]`::
 	Generate a diffstat. By default, as much space as necessary
 	will be used for the filename part, and the rest for the graph

@@ -318,12 +319,14 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
+[[name_only]]
 `--name-only`::
 	Show only the name of each changed file in the post-image tree.
 	The file names are often encoded in UTF-8.
 	For more information see the discussion about encoding in the linkgit:git-log[1]
 	manual page.
 
+[[name_status]]
 `--name-status`::
 	Show only the name(s) and status of each changed file. See the description
 	of the `--diff-filter` option on what the status letters mean.

@@ -417,6 +420,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
+[[ignore_all_space]]
 `ignore-all-space`::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.

@@ -432,6 +436,7 @@ endif::git-diff[]
 	used to override configuration settings. It is the same as
 	`--color-moved-ws=no`.
 
+[[word_diff]]
 `--word-diff[=<mode>]`::
 	By default, words are delimited by whitespace; see
 	`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and

base-commit: 0ffa3e35c7c82ab8d0de226149fb03b3f7674d05

gitgitgadget

This goes against what you said earlier, which was

Perhaps (--cached|--staged) or have two lines (i.e., turn the range diff into

or something).

And this is the other way around.

Other than that, the rest, including the resurrection of AUTO_MERGE, looked OK.

Clarification.

The point is that there is a difference between giving wider exposure to "--staged" as an accepted synonym and swapping offical option with the synonym, let alone deprecating "--cached".

You may have heard from several users that they like the word "staged", but I am sure there are more than several thousand users who have been using Git since before the synonym was introduced.

Ah, good point. Thanks for noticing.

I'll add this squashable fix-up on top before queuing; the change to the code is because otherwise this change would break a test.

Thanks.

 Documentation/git-diff.adoc | 8 ++++----
 builtin/diff.c              | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

index f15e56633e..42360f9b5e 100644
@@ -10,7 +10,7 @@ SYNOPSIS
 --------
 [synopsis]
 git diff [<options>] [<commit>] [--] [<path>...]
-git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]
+git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]
 git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
 git diff [<options>] <commit>...<commit> [--] [<path>...]
 git diff [<options>] <blob> <blob>

@@ -47,7 +47,7 @@ to diff.
 	difference. All such pathspecs must be relative as they
 	apply to both sides of the diff.
 
-`git diff [<options>] --staged [--merge-base] [<commit>] [--] [<path>...]`::
+`git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]`::
 
 	This form is to view the changes you staged for the next
 	commit relative to the named _<commit>_.  Typically you

@@ -55,10 +55,10 @@ to diff.
 	do not give _<commit>_, it defaults to `HEAD`.
 	If `HEAD` does not exist (e.g. unborn branches) and
 	_<commit>_ is not given, it shows all staged changes.
-	`--cached` is a synonym of `--staged`.
+	`--staged` is a synonym of `--cached`.
 +
 If `--merge-base` is given, instead of using _<commit>_, use the merge base
-of _<commit>_ and `HEAD`.  `git diff --cached --merge-base A` is equivalent to
+of _<commit>_ and `HEAD`.  `git diff --staged --merge-base A` is equivalent to
 `git diff --staged $(git merge-base A HEAD)`.
 
 `git diff [<options>] [--merge-base] <commit> [--] [<path>...]`::

index 18b1083e98..13fe8a21e0 100644
@@ -31,7 +31,7 @@
 
 static const char builtin_diff_usage[] =
 "git diff [<options>] [<commit>] [--] [<path>...]\n"
-"   or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n"
+"   or: git diff [<options>] (--cached|--staged) [--merge-base] [<commit>] [--] [<path>...]\n"
 "   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
 "   or: git diff [<options>] <commit>...<commit> [--] [<path>...]\n"
 "   or: git diff [<options>] <blob> <blob>\n"

An offtopic tangent but didn't we repeatedly float ideas to drop support for AsciiDoc, make sure our documentation set renders well only with AsciiDoctor, and tell folks who do not use AsciiDoctor to use pre-rendered documentation pages from git-htmldocs.git and git-manpages.git repositories at https://git.kernel.org/pub/scm/git/
during the past several months?

Perhaps I should add an entry to the BreakingChanges document (well, I know I know I do not think it belongs there, but since we hit this so many times already .....).

For sideline readers, some of this is documented in "git help cli" in the "NOTES ON FREQUENTLY CONFUSED OPTIONS" section.

D. Ben Knoble

Yeah, that's what I was hinting at near the bottom of my message. :)

But it's a big enough change that this series should probably just accept the ugly syntax for now, rather than waiting for us to drop python asciidoc support.

I'm not sure if it actually rises to the level of BreakingChanges. It is a build issue, not a user-facing one. And there is an easy workaround that can be applied anywhere for platforms that can't or don't want to use asciidoctor. So it may cause some slight hassle for packagers or those who build themselves, but it's not really breaking anybody.

-Peff

Yup, agreed. Improvements for these examples do not have to be held hostage on the toolchain support.

In any case, I'll queue another SQUASH??? commit on top of the topic until v3 materiazlies to fix these issues we have accumulated so far.

index 2dc54fa00e..bb46fd065b 100644
@@ -201,8 +201,7 @@ diff" algorithm internally.
 
 include::diff-algorithm-option.adoc[]
 
-[[stat]]
-`--stat[=<width>[,<name-width>[,<count>]]]`::
+`--stat[=<width>[,<name-width>[,<count>]]]`[[stat]]::
 	Generate a diffstat. By default, as much space as necessary
 	will be used for the filename part, and the rest for the graph
 	part. Maximum width defaults to terminal width, or 80 columns

@@ -319,15 +318,13 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
-[[name_only]]
-`--name-only`::
+`--name-only`[[name_only]]::
 	Show only the name of each changed file in the post-image tree.
 	The file names are often encoded in UTF-8.
 	For more information see the discussion about encoding in the linkgit:git-log[1]
 	manual page.
 
-[[name_status]]
-`--name-status`::
+`--name-status`[[name_status]]::
 	Show only the name(s) and status of each changed file. See the description
 	of the `--diff-filter` option on what the status letters mean.
 	Just like `--name-only` the file names are often encoded in UTF-8.

@@ -420,8 +417,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
-[[ignore_all_space]]
-`ignore-all-space`::
+`ignore-all-space`[[ignore_all_space]]::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.
 `allow-indentation-change`::

@@ -436,8 +432,7 @@ endif::git-diff[]
 	used to override configuration settings. It is the same as
 	`--color-moved-ws=no`.
 
-[[word_diff]]
-`--word-diff[=<mode>]`::
+`--word-diff[=<mode>]`[[word_diff]]::
 	By default, words are delimited by whitespace; see
 	`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and
 	must be one of:

And I realized that we need yet another SQUASH to address "isn't it a value of another option?" point.

SQUASH???

it is likely that the annotation was meant to go with --dashed-option

index bb46fd065b..dbac3b8275 100644
@@ -417,7 +417,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
-`ignore-all-space`[[ignore_all_space]]::
+`ignore-all-space`::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.
 `allow-indentation-change`::

@@ -783,7 +783,7 @@ endif::git-format-patch[]
 	more whitespace characters to be equivalent.
 
 `-w`::
-`--ignore-all-space`::
+`--ignore-all-space`[[ignore_all_space]]::
 	Ignore whitespace when comparing lines.  This ignores
 	differences even if one line has whitespace where the other
 	line has none.

Thanks, both of these squashes look good to me, and address all the issues I saw.

-Peff

Sorry, that's embarrassing, I didn't mean to include this change. I did an experimental rewrite to see what it would like to rename --cached to --staged, decided it would be better to keep the scope small, and I thought I'd undone it before submitting it.

Will take this out.

Good to hear.

Thanks for this, I don't know how to apply a patch from an email but I'll ask in the Discord to try to learn how. Same for the other changes.

As mentioned in Discord, when Junio mentions something along the lines of "I'll queue another SQUASH??? commit" , it means he would've already queued the SQUASH commit in the topic branch in his tree. You can view the same using something like:

  $ git remote add jch https://github.com/gitster/git
  $ git fetch jch je/doc-git-diff-examples
  $ git log FETCH_HEAD

Then on your local topic branch, you can do:

  $ git cherry-pick --no-commit <List_of_SQUASH_commit_ID...>

Hope this helps.

Sivaraam

It might be easier to fetch from me, find these squash commits from 'seen' ("git log seen" is your friend), and cherry pick them on top of what you have.