-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
+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.
+ 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
You need at least one <commit>. Specifying more than one
<commit> obviously means you are trying an Octopus.
-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.
+'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.
+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.)
- 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."
-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
-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
-* 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.
-The chosen merge strategy merges the two commits into a single
-When things merge cleanly, this is what happens:
-1. The results are updated both in the index file and in your
-2. Index file is written out as a tree;
-3. The tree gets committed; and
-4. The `HEAD` pointer gets advanced.
-Because of 2., we require that the original state of the index
-file matches exactly the current `HEAD` commit; otherwise we
-will write out your local changes already registered in your
-index file along with the merge result, which is not good.
-Because 1. involves only those paths differing between your
-branch and the branch you are merging
-(which is typically a fraction of the whole tree), you can
-have local modifications in your working tree as long as they do
-not overlap with what the merge updates.
-When there are conflicts, the following happens:
-1. `HEAD` stays the same.
-2. Cleanly merged paths are updated both in the index file and
+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
+This behavior can be suppressed with the `--no-ff` option.
-3. For conflicting paths, the index file records up to three
- versions; stage1 stores the version from the common ancestor,
- stage2 from `HEAD`, and stage3 from the other branch (you
+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
+A merged version reconciling the changes from all branches to be
+merged is committed, and your `HEAD`, index, and working tree are
+updated to it. It is possible to have modifications in the working
+tree as long as they do not overlap; the update will preserve them.
+When it is not obvious how to reconcile the changes, the following
+1. The `HEAD` pointer stays the same.
+2. The `MERGE_HEAD` ref is set to point to the other branch head.
+3. Paths that merged cleanly are updated both in the index file and
+4. For conflicting paths, the index file records up to three
+ versions: stage 1 stores the version from the common ancestor,
+ stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
can inspect the stages with `git ls-files -u`). The working
tree files contain the result of the "merge" program; i.e. 3-way
- merge results with familiar conflict markers `<<< === >>>`.
-4. No other changes are done. In particular, the local
+ merge results with familiar conflict markers `<<<` `===` `>>>`.
+5. No other changes are made. In particular, the local
modifications you had before you started merge will stay the
same and the index entries for them stay as they were,
+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
mergetool which will work you through the merge.
* Look at the diffs. `git diff` will show a three-way diff,
- highlighting changes from both the HEAD and their versions.
+ highlighting changes from both the `HEAD` and `MERGE_HEAD`
- * Look at the diffs on their own. `git log --merge -p <path>`
- will show diffs first for the HEAD version and then
+ * Look at the diffs from each branch. `git log --merge -p <path>`
+ will show diffs first for the `HEAD` version and then the
* 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.
+ common ancestor, `git show :2:filename` shows the `HEAD`
+ version, and `git show :3:filename` shows the `MERGE_HEAD`
release/version name would be acceptable.
+ 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.