Re: [PATCH] Documentation/git-merge: at least one <remote> not two

[Junio C Hamano <gitster@pobox.com>]

jidanni@jidanni.org writes:

> Make SYNOPSIS match usage message
>
> Signed-off-by: jidanni <jidanni@jidanni.org>
> ---
>  Documentation/git-merge.txt |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index f7be584..a3ac828 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -10,7 +10,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> -	[-m <msg>] <remote> <remote>...
> +	[-m <msg>] <remote>...
>  'git merge' <msg> HEAD <remote>...

The original uses ellipses for the first-class UI syntax as "zero or
more", while it means "one or more" in the description for the original
syntax, which is inconsistent, and you are matching them by making both
use "one or more" interpretation.

Two issues:

 * Are there similar breakages like this in the documentation and the
   usage text?  It would be a good idea to make the ellipses to mean the
   same thing everywhere, and a janitorial patch series that would fix
   the "ellipses" breakage (and nothing else) may be a good thing to
   have.  But before going that route...

 * Is it a good idea to standardize on "one or more" semantics?  I suspect
   we would rather want to standardize on "zero or more", because it would
   be more natural to say:

    $ git diff [--] <paths>...

   to mean "You can give paths if you want to but you do not have to".  If
   ellipses meant "one or more", you have to say this instead:

    $ git diff [--] [<paths>...]

While I prefer "zero or more" because  I think it is more logical, if the
preparatory study for the first issue reveals that we use "one or more" a
lot more often, it might be easier to standardize on that interpretation.

Oh, you also need to give ellipses to the usage string for the original
syntax in builtin-merge.c to match SYNOPSIS and usage string.

Thanks.