[PATCH] doc: git-diff: rewrite EXAMPLES section

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

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.

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.

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>
---
    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(-)

diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index e605d28678..2dc54fa00e 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -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
diff --git a/Documentation/git-diff.adoc b/Documentation/git-diff.adoc
index 272331afba..8d9de30f64 100644
--- a/Documentation/git-diff.adoc
+++ b/Documentation/git-diff.adoc
@@ -23,6 +23,9 @@ 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.
 
+The <<EXAMPLES,EXAMPLES>> section has examples of the most common ways
+to diff.
+
 `git diff [<options>] [--] [<path>...]`::
 
 	This form is to view the changes you made relative to
@@ -160,78 +163,90 @@ section "3-Way Merge" for detailed information.
 
 include::diff-format.adoc[]
 
+[[EXAMPLES]]
 EXAMPLES
 --------
 
-Various ways to check your working tree::
-+
-------------
-$ git diff            <1>
-$ git diff --cached   <2>
-$ git diff HEAD       <3>
-$ git diff AUTO_MERGE <4>
-------------
-+
-<1> Changes in the working tree not yet staged for the next commit.
-<2> Changes between the index and your last commit; what you
-    would be committing if you run `git commit` without `-a` option.
-<3> Changes in the working tree since your last commit; what you
-    would be committing if you run `git commit -a`
-<4> Changes in the working tree you've made to resolve textual
-    conflicts so far.
-
-Comparing with arbitrary commits::
-+
-------------
-$ git diff test            <1>
-$ git diff HEAD -- ./test  <2>
-$ git diff HEAD^ HEAD      <3>
-------------
-+
-<1> Instead of using the tip of the current branch, compare with the
-    tip of "test" branch.
-<2> Instead of comparing with the tip of "test" branch, compare with
-    the tip of the current branch, but limit the comparison to the
-    file "test".
-<3> Compare the version before the last commit and the last commit.
-
-Comparing branches::
-+
-------------
-$ git diff topic master    <1>
-$ git diff topic..master   <2>
-$ git diff topic...master  <3>
-------------
-+
-<1> Changes between the tips of the topic and the master branches.
-<2> Same as above.
-<3> Changes that occurred on the master branch since when the topic
-    branch was started off it.
+Diff uncommitted changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+`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`
+|===
+
+Diff a specific file/directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can usually put a filename or directory at the end to restrict the
+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 unstaged changes for `file.txt`
+|`git diff -- file.txt`
+
+|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 between the `topic` branch and the `main` branch
+|`git diff main topic`
+
+|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`>>
+
+|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`>>
+|===
+
+Options to display the diff in another way
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[cols="1,1"]
+|===
+|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.
 
 CONFIGURATION
 -------------

base-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e
-- 
gitgitgadget