diff options
| author |  Martin Ågren <martin.agren@gmail.com> | 2020-07-13 21:10:09 +0200 |
|---|---|---|
| committer |  Junio C Hamano <gitster@pobox.com> | 2020-07-13 12:47:38 -0700 |
| commit | 78b76d310f3e9c0cc1e990ed93f58711e48d9ab2 (patch) | |
| tree | a5d5ed92f5f91c2106d31bb2e6dc9d70cbf407cb | |
| parent | git-diff.txt: don't mark required argument as optional (diff) | |
| download | tgif-78b76d310f3e9c0cc1e990ed93f58711e48d9ab2.tar.xz | |
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>
| -rw-r--r-- | Documentation/git-diff.txt | 13 |
1 files 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 |