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.
-
--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.
+include::merge-options.txt[]
-<head>::
- our branch head commit.
+-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.
-<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 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.
+
+The chosen merge strategy merges the two commits into a single
+new source tree.
+When things merge cleanly, this is what happens:
+
+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 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 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, the following happens:
+
+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 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
+ 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`.
+
+HOW CONFLICTS ARE PRESENTED
+---------------------------
+
+During a merge, the working tree files are updated to reflect the result
+of the merge. Among the changes made to the common ancestor's version,
+non-overlapping ones (that is, you changed an area of the file while the
+other side left that area intact, or vice versa) are incorporated in the
+final result verbatim. When both sides made changes to the same area,
+however, git cannot randomly pick one side over the other, and asks you to
+resolve it by leaving what both sides did to that area.
+
+By default, git uses the same style as that is used by "merge" program
+from the RCS suite to present such a conflicted hunk, like this:
+
+------------
+Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+=======
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
+------------
+
+The area where a pair of conflicting changes happened is marked with markers
+"`<<<<<<<`", "`=======`", and "`>>>>>>>`". The part before the "`=======`"
+is typically your side, and the part afterwards is typically their side.
+
+The default format does not show what the original said in the conflicting
+area. You cannot tell how many lines are deleted and replaced with
+Barbie's remark on your side. The only thing you can tell is that your
+side wants to say it is hard and you'd prefer to go shopping, while the
+other side wants to claim it is easy.
+
+An alternative style can be used by setting the "merge.conflictstyle"
+configuration variable to "diff3". In "diff3" style, the above conflict
+may look like this:
+
+------------
+Here are lines that are either unchanged from the common
+ancestor, or cleanly resolved because only one side changed.
+<<<<<<< yours:sample.txt
+Conflict resolution is hard;
+let's go shopping.
+|||||||
+Conflict resolution is hard.
+=======
+Git makes conflict resolution easy.
+>>>>>>> theirs:sample.txt
+And here is another line that is cleanly resolved or unmodified.
+------------
+
+In addition to the "`<<<<<<<`", "`=======`", and "`>>>>>>>`" markers, it uses
+another "`|||||||`" marker that is followed by the original text. You can
+tell that the original just stated a fact, and your side simply gave in to
+that statement and gave up, while the other side tried to have a more
+positive attitude. You can sometimes come up with a better resolution by
+viewing the original.
+
+
+HOW TO RESOLVE CONFLICTS
+------------------------
+
+After seeing a conflict, you can do two things:
+
+ * 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
+ 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.
+
+You can work through the conflict with a number of tools:
+
+ * 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,
+ highlighting changes from both the HEAD and remote versions.
+
+ * Look at the diffs on their own. 'git log --merge -p <path>'
+ will show diffs first for the HEAD version and then the
+ remote 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 the remote version.
+
+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