Re: git-merge: inconsistent manual page.

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

  Junio C Hamano [off-list ref] 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(-)

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index bca4212..a056b40 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt

@@ -11,6 +11,7 @@ SYNOPSIS
 [verse]
 'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
 	[-m <msg>] <remote> <remote>...
+'git-merge' <msg> HEAD <remote>...
 
 DESCRIPTION
 -----------

@@ -43,6 +44,11 @@ If you tried a merge which resulted in a complex conflicts and
 would want to start over, you can recover with
 gitlink:git-reset[1].
 
+The second syntax (<msg> `HEAD` <remote>) is supported for
+historical reasons.  Do not use it from the command line or in
+new scripts.
+
+
 CONFIGURATION
 -------------