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

From: Sergey Organov <[email-masked]>
Date: Wed, 08 Oct 2014 00:32:35 +0400

Junio C Hamano <[email-masked]> writes:

> Sergey Organov <[email-masked]> 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 <[email-masked]>
>> ---
>
> 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.