git-merge(1)
============
-v0.99.6, Sep 2005
NAME
----
-git-merge - Grand Unified Merge Driver
+git-merge - Join two or more development histories together
SYNOPSIS
--------
-'git-merge' [-n] [-s <strategy>]... <msg> <head> <remote> <remote>...
-
+[verse]
+'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
+ [-m <msg>] <remote> <remote>...
+'git merge' <msg> HEAD <remote>...
DESCRIPTION
-----------
-This is the top-level user interface to the merge machinery
+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
-------
--n::
- Do not show diffstat at the end of the merge.
+include::merge-options.txt[]
--s <strategy>::
- use that merge strategy; can be given more than once to
- specify them in the order they should be tried. If
- there is no `-s` option, built-in list of strategies is
- used instead.
+-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.
-
-<remote>::
- other branch head merged into our branch. You need at
+<remote>...::
+ Other branch heads to merge into our branch. You need at
least one <remote>. Specifying more than one <remote>
obviously means you are trying an Octopus.
+include::merge-strategies.txt[]
+
+
+If you tried a merge which resulted in a complex conflicts and
+would want to start over, you can recover with 'git-reset'.
+
+CONFIGURATION
+-------------
+include::merge-config.txt[]
+
+branch.<name>.mergeoptions::
+ Sets default options for merging into branch <name>. The syntax and
+ supported options are equal to that of 'git-merge', but option values
+ containing whitespace characters are currently not supported.
+
+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 involved through 'git pull':
+ you are tracking an upstream repository, committed no local
+ changes and now you want to update to a newer upstream revision.
+ Your `HEAD` (and the index) is updated to at point 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 them both 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.
+When things cleanly merge, these things happen:
+
+1. The results are updated both in the index file and in your
+ working tree;
+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 to match 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 the paths different between your
+branch and the remote branch you are pulling from during the
+merge (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, these things happen:
+
+1. `HEAD` stays the same.
+
+2. Cleanly merged paths are updated both in the index file and
+ in your working tree.
+
+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 remote branch (you
+ can inspect the stages with `git ls-files -u`). The working
+ tree files have the result of "merge" program; i.e. 3-way
+ merge result with familiar conflict markers `<<< === >>>`.
+
+4. No other changes are done. 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,
+ i.e. matching `HEAD`.
+
+After seeing a conflict, you can do two things:
+
+ * Decide not to merge. The only clean-up 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
+ be used for this.
+
+ * Resolve the conflicts. `git diff` would report only the
+ conflicting paths because of the above 2. and 3.
+ Edit the working tree files into a desirable shape
+ ('git mergetool' can ease this task), 'git-add' or 'git-rm'
+ them, to make the index file contain what the merge result
+ should be, and run 'git-commit' to commit the result.
+
+
+SEE ALSO
+--------
+linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
+linkgit:gitattributes[5],
+linkgit:git-reset[1],
+linkgit:git-diff[1], linkgit:git-ls-files[1],
+linkgit:git-add[1], linkgit:git-rm[1],
+linkgit:git-mergetool[1]
Author
------
-Written by Junio C Hamano <junkio@cox.net>
+Written by Junio C Hamano <gitster@pobox.com>
Documentation
GIT
---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[1] suite