Re: [PATCH] git-merge: mutually match SYNOPSIS and "usage".
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 7, 2014, 18:34 UTC
- Message-ID
- <xmqq4mvfg24e.fsf@gitster.dls.corp.google.com>
- In-Reply-To
- <87wq8cnla9.fsf@osv.gnss.ru>
Sergey Organov <sorganov@gmail.com> writes:
Show 9 quoted lines
> 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.
Show 34 quoted lines
> 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