[1/2] git-diff.txt: don't mark required argument as optional
diff mbox series

Message ID 77e4442ae51a968d460b2329fc39b6a5e96902b0.1594666410.git.martin.agren@gmail.com
State New
Headers show
Series
  • git-diff.txt: reorder possible usages
Related show

Commit Message

Martin Ågren July 13, 2020, 7:10 p.m. UTC
Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
to

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

to effectively add

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

as another valid invocation. Which makes sense.

Further down, in the description, it left the existing entry for

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

intact and added a new entry on

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

where it says that "[t]his form is to view the results of a merge
commit" and details how "the first listed commit must be the merge
itself". But one possible instantiation of this form is `git diff
<commit> <commit>` for which the added text doesn't really apply.

Remove the brackets so that we lose this overlap between the two
descriptions. We can still use the more compact representation in the
synopsis.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-diff.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Comments

Junio C Hamano July 13, 2020, 7:45 p.m. UTC | #1
Martin Ågren <martin.agren@gmail.com> writes:

> Commit b7e10b2ca2 ("Documentation: usage for diff combined commits",
> 2020-06-12) modified the synopsis by adding an optional "[<commit>...]"
> to
>
>   'git diff' [<options>] <commit> <commit> [--] [<path>...]
>
> to effectively add
>
>   'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]
>
> as another valid invocation. Which makes sense.
>
> Further down, in the description, it left the existing entry for
>
>   'git diff' [<options>] <commit> <commit> [--] [<path>...]
>
> intact and added a new entry on
>
>   'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
>
> where it says that "[t]his form is to view the results of a merge
> commit" and details how "the first listed commit must be the merge
> itself". But one possible instantiation of this form is `git diff
> <commit> <commit>` for which the added text doesn't really apply.
>
> Remove the brackets so that we lose this overlap between the two
> descriptions. We can still use the more compact representation in the
> synopsis.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
>  Documentation/git-diff.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 1018110ddc..c613e71ca4 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -69,7 +69,7 @@ files on disk.
>  	one side is omitted, it will have the same effect as
>  	using HEAD instead.
>  
> -'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
> +'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::

Thanks.

>  
>  	This form is to view the results of a merge commit.  The first
>  	listed <commit> must be the merge itself; the remaining two or

Patch
diff mbox series

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 1018110ddc..c613e71ca4 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -69,7 +69,7 @@  files on disk.
 	one side is omitted, it will have the same effect as
 	using HEAD instead.
 
-'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
+'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]::
 
 	This form is to view the results of a merge commit.  The first
 	listed <commit> must be the merge itself; the remaining two or