[PATCH 2/2] git-diff.txt: reorder possible usages
- From
- Martin Ågren <martin.agren@gmail.com>
- Date
- Jul 13, 2020, 19:10 UTC
- Message-ID
- <280943ef56a2a777ab0162b8ec4ba0166cc2095c.1594666410.git.martin.agren@gmail.com>
- In-Reply-To
- <cover.1594666410.git.martin.agren@gmail.com>
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> --- 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