git-diff.txt: reorder possible usages

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>

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index c613e71ca4116620bb34c7d5d0dc814b663c47a2..727f24d16ec931e4bb23f33f4f44f5c341e497f0 100644 (file)
--- 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