From: Junio C Hamano <gitster@pobox•com>
To: Sergey Organov <sorganov@gmail•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH] git-merge: mutually match SYNOPSIS and "usage".
Date: Tue, 07 Oct 2014 11:34:41 -0700 [thread overview]
Message-ID: <xmqq4mvfg24e.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <87wq8cnla9.fsf@osv.gnss.ru> (Sergey Organov's message of "Tue, 7 Oct 2014 15:54:58 +0400")
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
next prev parent reply other threads:[~2014-10-07 18:34 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-10-07 11:54 [PATCH] git-merge: mutually match SYNOPSIS and "usage" Sergey Organov
2014-10-07 18:34 ` Junio C Hamano [this message]
2014-10-07 20:32 ` Sergey Organov
2014-10-07 21:31 ` Junio C Hamano
2014-10-08 10:12 ` Sergey Organov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq4mvfg24e.fsf@gitster.dls.corp.google.com \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=sorganov@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox