[verse]
'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
[-m <msg>] <remote> <remote>...
+'git-merge' <msg> HEAD <remote>...
DESCRIPTION
-----------
This is the top-level interface to the merge machinery
which drives multiple merge strategy scripts.
+The second syntax (<msg> `HEAD` <remote>) 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> <remote>`.
+
OPTIONS
-------
include::merge-options.txt[]
-<msg>::
+-m <msg>::
The commit message to be used for the merge commit (in case
it is created). The `git-fmt-merge-msg` script can be used
to give a good default for automated `git-merge` invocations.
-<head>::
- Our branch head commit. This has to be `HEAD`, so new
- syntax does not require it
-
<remote>::
Other branch head merged into our branch. You need at
least one <remote>. Specifying more than one <remote>
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].
+linkgit:git-reset[1].
CONFIGURATION
-------------
---------------
A merge is always between the current `HEAD` and one or more
-remote branch heads, and the index file must exactly match the
+commits (usually, branch head or tag), and the index file must
+exactly match the
tree of `HEAD` commit (i.e. the contents of the last commit) when
it happens. In other words, `git-diff --cached HEAD` must
report no changes.
[NOTE]
-This is a bit of lie. In certain special cases, your index are
-allowed to be different from the tree of `HEAD` commit. The most
+This is a bit of a lie. In certain special cases, your index is
+allowed to be different from the tree of the `HEAD` commit. The most
notable case is when your `HEAD` commit is already ahead of what
is being merged, in which case your index can have arbitrary
-difference from your `HEAD` commit. Otherwise, your index entries
-are allowed have differences from your `HEAD` commit that match
-the result of trivial merge (e.g. you received the same patch
-from external source to produce the same result as what you are
+differences from your `HEAD` commit. Also, your index entries
+may have differences from your `HEAD` commit that match
+the result of a trivial merge (e.g. you received the same patch
+from an external source to produce the same result as what you are
merging). For example, if a path did not exist in the common
ancestor and your head commit but exists in the tree you are
merging into your repository, and if you already happen to have
SEE ALSO
--------
-gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
+linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
+linkgit:gitattributes[5]
Author
GIT
---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite