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@xxxxxxxxx>
---
Junio C Hamano <gitster@xxxxxxxxx> 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
-------------
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
