patchgit-merge: mutually match SYNOPSIS and "usage".

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>
---
 Documentation/git-merge.txt | 6 ++----
 builtin/merge.c             | 2 +-
 2 files changed, 3 insertions(+), 5 deletions(-)

Sergey Organov <sorganov@gmail.com> writes:

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.

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

Well, I thought they are related, sorry.

OK, noticed.

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.

Any particular suggestion?

Thanks.

Sergey Organov <sorganov@gmail.com> writes:

The thing is, with "-m <msg>" we will never fall into the traditional syntax, hence "git merge -m <msg> <msg> HEAD <commit>" appear to be allowed with "git merge [options] <msg> HEAD <commit>...", but it is not.

And the inverse is not true (an obvious example is "git merge $branch", even though it does not have "-m <msg>" it uses the modern & common.

So the updated SYNOPSIS is not really helping.

I was going to suggest "explain how the traditional syntax is triggered in the DESCRIPTION section", but it turns out that we already do that.

      The second syntax (<msg> HEAD <commit>...) is supported for
      historical reasons. Do not use it from the command line or in
      new scripts. It is the same as git merge -m <msg> <commit>....

Strictly speaking, I think it is not qute "the same"---I recall vaguely that it broke tests if you replace the traditional-style invocation in 'git pull' with the -m <msg> syntax, but I do not have details handy; you may want to try it out if you are interested.

So I would think

	SYNOPSIS
        	git merge [options] <commit>...
		git merge [options] <msg> HEAD <commit>...
                git merge --abort

should be sufficient, possibly with some clarification on "The second syntax" paragraph in the DESCRIPTION section.

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

No. When you see:

  git merge [options] [-m <msg>] <commit>...

Isn't it obvious that 'options' don't include "-m <msg>", so
  
  git merge [options] <msg> HEAD <commit>...

form will never apply when you have "-m <msg>" in the command, exaclty because 'options' don't include "-m <msg"?

Sure, and this is covered as well.

I disagree, see above.

I still think that for somewhat messy historical situation, the suggested syntax description is good enough.