jidanni@xxxxxxxxxxx writes:
> Make SYNOPSIS match usage message
>
> Signed-off-by: jidanni <jidanni@xxxxxxxxxxx>
> ---
> 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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
