Re: [PATCH] git-merge: mutually match SYNOPSIS and "usage".

From: Sergey Organov <sorganov@gmail.com>
Date: Oct 7, 2014, 20:32 UTC
Message-ID: <87bnpnsjrw.fsf@osv.gnss.ru>
In-Reply-To: <xmqq4mvfg24e.fsf@gitster.dls.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 13 quoted lines

> 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.

Well, I thought they are related, sorry.

> 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".

OK, noticed.

> 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>...]".

I was looking at the merge.c code, and that's how it seems to work. You can get new semantics without -m, and you can't get old semantics with -m, isn't it? It looks like the set of descriptions I produced is formally correct.

> 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.

Any particular suggestion?

Thanks.

-- 
Sergey.