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