undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-diff.txt: reorder possible usages

Browse Source 
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>
This commit is contained in:
Martin Ågren 2020-07-13 21:10:09 +02:00 committed by Junio C Hamano
parent bc5482e9db
commit 78b76d310f
1 changed files with 7 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
Documentation/git-diff.txt
View File

@ -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