From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 07 Oct 2014 18:34:41 GMT
Subject: Re: [PATCH] git-merge: mutually match SYNOPSIS and "usage".
Message-ID: <xmqq4mvfg24e.fsf@gitster.dls.corp.google.com>
In-Reply-To: <87wq8cnla9.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

> SYNOPSIS section of the git-merge manual page had outdated explicit
> list of options.
>
> "usage" returned by 'git merge -h' didn't have "-m <msg>" that is one
> of essential distinctions between obsolete invocation form and the
> recent one.
>
> Signed-off-by: Sergey Organov <sorganov@gmail.com>
> ---

Please do not do two unrelated things in a single change.

It may be a clear and very welcome improvement to change from
"explicitly list only often used options" to "just say [options] and
have the list of options and their descriptions".

I am not sure about the other change to single out "-m <msg>",
especially marking it as optional by enclosing it inside "[-m
<msg>]", makes much sense, as that is still not very easily
distinguishable from "git merge [options] [<commit>...]".  In other
words, I agree with your motivation to call for attention that the
command behaves differently with and without "-m", but I do not
think that part of the change in this patch achieves it well.

>  Documentation/git-merge.txt | 6 ++----
>  builtin/merge.c             | 2 +-
>  2 files changed, 3 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index cf2c374..e24a1d4 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -9,10 +9,8 @@ git-merge - Join two or more development histories together
>  SYNOPSIS
>  --------
>  [verse]
> -'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
> -	[-s <strategy>] [-X <strategy-option>] [-S[<key-id>]]
> -	[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]
> -'git merge' <msg> HEAD <commit>...
> +'git merge' [options] [-m <msg>] [<commit>...]
> +'git merge' [options] <msg> HEAD <commit>...
>  'git merge' --abort
>  
>  DESCRIPTION
> diff --git a/builtin/merge.c b/builtin/merge.c
> index dff043d..086502f 100644
> --- a/builtin/merge.c
> +++ b/builtin/merge.c
> @@ -40,7 +40,7 @@ struct strategy {
>  };
>  
>  static const char * const builtin_merge_usage[] = {
> -	N_("git merge [options] [<commit>...]"),
> +	N_("git merge [options] [-m <msg>] [<commit>...]"),
>  	N_("git merge [options] <msg> HEAD <commit>"),
>  	N_("git merge --abort"),
>  	NULL