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@xxxxxxxxx>
---
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
--
2.28.0.rc0
