git-merge: inconsistent manual page.

Hello,

git-merge has inconsistent manual page:

1. In the SYNOPSIS, there is [-m <msg>], but OPTIONS section lacks it.
   The latter has just  description of <msg>, suggesting it could be
   used without -m, but SYNOPSIS doesn't reflect this. 

   BTW, git-merge options are described in
   Documentation/merge-options.txt that is also used fot git-pull
   options, and it's not clear for me if git-pull supports [-m
   <msg>]. Does it?

2. In the SYNOPSIS, there is no <head> that is described in the
   OPTIONS.

Overall, it seems that either SYNOPSIS should be changed (see patch below), or historical syntax should be wiped from the manual page.

Sergei Organov <osv@javad.com> writes:

This is not quite right, I am afraid. "git merge" used to take its parameters in quite an exotic order, and we still do support it as we do not break people's existing setups:

	git-merge "$message" HEAD $list_of_merged_refs

where the second parameter is always HEAD. This is the only form that accepts the message without -m (see ll.230- in the git-merge script).

But we do not _want_ to advertise this funny syntax. Humans and newly written scripts should express the above as:

	git merge -m "$message" $list_of_merged_refs

It shouldn't; the merge message is prepared by git-pull to describe what got merged from where for you (see the last few lines in the git-pull script).

See above.  We do not want to advertise the crazy syntax.

Subject: git-merge: document but discourage the historical syntax

Historically "git merge" took its command line arguments in a rather strange order. Document the historical syntax, and also document clearly that it is not encouraged in new scripts.

There is no reason to deprecate the historical syntax, as the current code can sanely tell which syntax the caller is using, and existing scripts by people do use the historical syntax.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

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

  > See above.  We do not want to advertise the crazy syntax.

  By the way, I kept saying "crazy" above, but the thing is that
  when Linus did that "crazy" syntax, it was not crazy at all.
  Simply it did not matter, as nobody was supposed to use "git
  merge" from the command line.

  Instead, when merging a local branch, you would just have said:

          $ git pull . $my_other_branch

  It became a "crazy historical syntax" only after people started
  talking about using it from the command line, giving it other
  command line options.  And at that point, we introduced -m flag
  and stopped requiring the second token 'HEAD'.

  With that in mind, this might be a better alternative.

 Documentation/git-merge.txt |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

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

OK, your patch is better than what I've suggested. The only thing that your patch seems to be missing is prepending -m to <msg>:: in the OPTIONS section. Yeah, it could be more strict to just describe <msg>, but if there were no historical syntax, then you'd put '-m <msg>' description in, right? So the latter might be better anyway.

Sergei Organov <osv@javad.com> writes:

Nah, you are absolutely right. We describe "-s <strategy>" under the headline with the leading "-s".

Will fix.