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>

Martin Ågren committed Jul 13, 2020 at 21:10 UTC 78b76d310f3e9c0cc1e990ed93f58711e48d9ab2

1 file changed +7 -6

Documentation/git-diff.txt

+7 -6

@@ -63,12 +63,6 @@ files on disk.

63 This is to view the changes between two arbitrary

64 <commit>.

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

67 -

68 - This is synonymous to the previous form. If <commit> on

69 - one side is omitted, it will have the same effect as

70 - using HEAD instead.

71 -

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

68 This form is to view the results of a merge commit. The first

@@ -78,6 +72,13 @@ files on disk.

72 For instance, if `master` names a merge commit, `git diff master

73 master^@` gives the same combined diff as `git show master`.

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

76 +

77 + This is synonymous to the earlier form (without the "..") for

78 + viewing the changes between two arbitrary <commit>. If <commit> on

79 + one side is omitted, it will have the same effect as

80 + using HEAD instead.

81 +

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

84 This form is to view the changes on the branch containing