From bc5482e9db9bbecbfcd3a45793af78d7e0a6a638 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20=C3=85gren?= <martin.agren@gmail.com>
Date: Mon, 13 Jul 2020 21:10:08 +0200
Subject: [PATCH 1/2] git-diff.txt: don't mark required argument as optional
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
to

  'git diff' [<options>] <commit> <commit> [--] [<path>...]

to effectively add

  'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]

as another valid invocation. Which makes sense.

Further down, in the description, it left the existing entry for

  'git diff' [<options>] <commit> <commit> [--] [<path>...]

intact and added a new entry on

  'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]

where it says that "[t]his form is to view the results of a merge
commit" and details how "the first listed commit must be the merge
itself". But one possible instantiation of this form is `git diff
<commit> <commit>` for which the added text doesn't really apply.

Remove the brackets so that we lose this overlap between the two
descriptions. We can still use the more compact representation in the
synopsis.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-diff.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 1018110ddc..c613e71ca4 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -69,7 +69,7 @@ files on disk.
 	one side is omitted, it will have the same effect as
 	using HEAD instead.
 
-'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
+'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::
 
 	This form is to view the results of a merge commit.  The first
 	listed <commit> must be the merge itself; the remaining two or

From 78b76d310f3e9c0cc1e990ed93f58711e48d9ab2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20=C3=85gren?= <martin.agren@gmail.com>
Date: Mon, 13 Jul 2020 21:10:09 +0200
Subject: [PATCH 2/2] git-diff.txt: reorder possible usages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The description of `git diff` goes through several different invocations
(numbering added by me):

  1. git diff [<options>] [--] [<path>...]
  2. git diff [<options>] --no-index [--] <path> <path>
  3. git diff [<options>] --cached [<commit>] [--] [<path>...]
  4. git diff [<options>] <commit> [--] [<path>...]
  5. git diff [<options>] <commit> <commit> [--] [<path>...]
  6. git diff [<options>] <commit>..<commit> [--] [<path>...]
  7. git diff [<options>] <commit> <commit>... <commit> [--] [<path>...]
  8. git diff [<options>] <commit>...<commit> [--] [<path>...]

It then goes on to say that "all of the <commit> in the above
description, except in the last two forms that use '..' notations, can
be any <tree>". The "last two" actually refers to 6 and 8. This got out
of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined
commits", 2020-06-12) which added item 7 to the mix.

As a further complication, after b7e10b2ca2 we also have some potential
confusion around "the '..' notation". The "..[.]" in items 6 and 8 are
part of the rev notation, whereas the "..." in item 7 is manpage
language for "one or more".

Move item 6 down, i.e., to between 7 and 8, to restore the ordering.
Because 6 refers to 5 ("synonymous to the previous form") we need to
tweak the language a bit.

An added bonus of this commit is that we're trying to steer users away
from `git diff <commit>..<commit>` and moving it further down probably
doesn't hurt.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-diff.txt | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index c613e71ca4..727f24d16e 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -63,12 +63,6 @@ files on disk.
 	This is to view the changes between two arbitrary
 	<commit>.
 
-'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
-
-	This is synonymous to the previous form.  If <commit> on
-	one side is omitted, it will have the same effect as
-	using HEAD instead.
-
 'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::
 
 	This form is to view the results of a merge commit.  The first
@@ -78,6 +72,13 @@ files on disk.
 	For instance, if `master` names a merge commit, `git diff master
 	master^@` gives the same combined diff as `git show master`.
 
+'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
+
+	This is synonymous to the earlier form (without the "..") for
+	viewing the changes between two arbitrary <commit>.  If <commit> on
+	one side is omitted, it will have the same effect as
+	using HEAD instead.
+
 'git diff' [<options>] <commit>\...<commit> [--] [<path>...]::
 
 	This form is to view the changes on the branch containing