DESCRIPTION
-----------
-Merges the history specified by <commit> into HEAD, optionally using a
-specific merge strategy.
+Incorporates changes from the named commits (since the time their
+histories diverged from the current branch) into the current
+branch. This command is used by 'git pull' to incorporate changes
+from another repository and can be used by hand to merge changes
+from one branch into another.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+ A---B---C topic
+ /
+ D---E---F---G master
+------------
+
+Then "`git merge topic`" will replay the changes made on the
+`topic` branch since it diverged from `master` (i.e., `E`) until
+its current commit (`C`) on top of `master`, and record the result
+in a new commit along with the names of the two parent commits and
+a log message from the user describing the changes.
+
+------------
+ A---B---C topic
+ / \
+ D---E---F---G---H master
+------------
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>...`.
+*Warning*: Running 'git merge' with uncommitted changes is
+discouraged: while possible, it leaves you in a state that is hard to
+back out of in the case of a conflict.
+
OPTIONS
-------
You need at least one <commit>. Specifying more than one
<commit> obviously means you are trying an Octopus.
-include::merge-strategies.txt[]
+PRE-MERGE CHECKS
+----------------
-If you tried a merge which resulted in complex conflicts and
-want to start over, you can recover with 'git-reset'.
+Before applying outside changes, you should get your own work in
+good shape and committed locally, so it will not be clobbered if
+there are conflicts. See also linkgit:git-stash[1].
+'git pull' and 'git merge' will stop without doing anything when
+local uncommitted changes overlap with files that 'git pull'/'git
+merge' may need to update.
-CONFIGURATION
--------------
-include::merge-config.txt[]
+To avoid recording unrelated changes in the merge commit,
+'git pull' and 'git merge' will also abort if there are any changes
+registered in the index relative to the `HEAD` commit. (One
+exception is when the changed index entries are in the state that
+would result from the merge already.)
-branch.<name>.mergeoptions::
- Sets default options for merging into branch <name>. The syntax and
- supported options are the same as those of 'git merge', but option
- values containing whitespace characters are currently not supported.
+If all named commits are already ancestors of `HEAD`, 'git merge'
+will exit early with the message "Already up-to-date."
+
+FAST-FORWARD MERGE
+------------------
+
+Often the current branch head is an ancestor of the named commit.
+This is the most common case especially when invoked from 'git
+pull': you are tracking an upstream repository, you have committed
+no local changes, and now you want to update to a newer upstream
+revision. In this case, a new commit is not needed to store the
+combined history; instead, the `HEAD` (along with the index) is
+updated to point at the named commit, without creating an extra
+merge commit.
+
+This behavior can be suppressed with the `--no-ff` option.
HOW MERGE WORKS
---------------
A merge is always between the current `HEAD` and one or more
-commits (usually, branch head or tag), and the index file must
-match the tree of `HEAD` commit (i.e. the contents of the last commit)
-when it starts out. In other words, `git diff --cached HEAD` must
-report no changes. (One exception is when the changed index
-entries are already in the same state that would result from
-the merge anyway.)
-
-Three kinds of merge can happen:
-
-* The merged commit is already contained in `HEAD`. This is the
- simplest case, called "Already up-to-date."
-
-* `HEAD` is already contained in the merged commit. This is the
- most common case especially when invoked from 'git pull':
- you are tracking an upstream repository, have committed no local
- changes and now you want to update to a newer upstream revision.
- Your `HEAD` (and the index) is updated to point at the merged
- commit, without creating an extra merge commit. This is
- called "Fast-forward".
-
-* Both the merged commit and `HEAD` are independent and must be
- tied together by a merge commit that has both of them as its parents.
- The rest of this section describes this "True merge" case.
+commits (usually a branch head or tag).
+
+Except in a fast-forward merge (see above), the branches to be
+merged must be tied together by a merge commit that has both of them
+as its parents.
+The rest of this section describes this "True merge" case.
The chosen merge strategy merges the two commits into a single
new source tree.
same and the index entries for them stay as they were,
i.e. matching `HEAD`.
+If you tried a merge which resulted in complex conflicts and
+want to start over, you can recover with `git reset --merge`.
+
HOW CONFLICTS ARE PRESENTED
---------------------------
* Decide not to merge. The only clean-ups you need are to reset
the index file to the `HEAD` commit to reverse 2. and to clean
- up working tree changes made by 2. and 3.; 'git-reset --hard' can
+ up working tree changes made by 2. and 3.; `git-reset --hard` can
be used for this.
* Resolve the conflicts. Git will mark the conflicts in
the working tree. Edit the files into shape and
- 'git-add' them to the index. Use 'git-commit' to seal the deal.
+ 'git add' them to the index. Use 'git commit' to seal the deal.
You can work through the conflict with a number of tools:
- * Use a mergetool. 'git mergetool' to launch a graphical
+ * Use a mergetool. `git mergetool` to launch a graphical
mergetool which will work you through the merge.
- * Look at the diffs. 'git diff' will show a three-way diff,
+ * Look at the diffs. `git diff` will show a three-way diff,
highlighting changes from both the HEAD and their versions.
- * Look at the diffs on their own. 'git log --merge -p <path>'
+ * Look at the diffs on their own. `git log --merge -p <path>`
will show diffs first for the HEAD version and then
their version.
- * Look at the originals. 'git show :1:filename' shows the
- common ancestor, 'git show :2:filename' shows the HEAD
- version and 'git show :3:filename' shows their version.
+ * Look at the originals. `git show :1:filename` shows the
+ common ancestor, `git show :2:filename` shows the HEAD
+ version and `git show :3:filename` shows their version.
EXAMPLES
release/version name would be acceptable.
+include::merge-strategies.txt[]
+
+CONFIGURATION
+-------------
+include::merge-config.txt[]
+
+branch.<name>.mergeoptions::
+ Sets default options for merging into branch <name>. The syntax and
+ supported options are the same as those of 'git merge', but option
+ values containing whitespace characters are currently not supported.
+
SEE ALSO
--------
linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],