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

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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.

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

diff --git c/Documentation/git-diff.adoc w/Documentation/git-diff.adoc
index f15e56633e..42360f9b5e 100644
--- c/Documentation/git-diff.adoc
+++ w/Documentation/git-diff.adoc
@@ -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>...]`::
diff --git c/builtin/diff.c w/builtin/diff.c
index 18b1083e98..13fe8a21e0 100644
--- c/builtin/diff.c
+++ w/builtin/diff.c
@@ -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"