2005-09-09 08:15:47 +00:00
|
|
|
git-merge(1)
|
|
|
|
============
|
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
2007-01-18 23:53:37 +00:00
|
|
|
git-merge - Join two or more development histories together
|
2005-09-09 08:15:47 +00:00
|
|
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2006-11-20 09:06:09 +00:00
|
|
|
[verse]
|
2008-06-30 06:09:04 +00:00
|
|
|
'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
|
2009-12-04 08:20:48 +00:00
|
|
|
[--[no-]rerere-autoupdate] [-m <msg>] <remote>...
|
2008-06-30 06:09:04 +00:00
|
|
|
'git merge' <msg> HEAD <remote>...
|
2005-09-09 08:15:47 +00:00
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
2006-11-20 09:06:09 +00:00
|
|
|
This is the top-level interface to the merge machinery
|
2005-09-09 08:15:47 +00:00
|
|
|
which drives multiple merge strategy scripts.
|
|
|
|
|
2007-10-30 18:54:11 +00:00
|
|
|
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>`.
|
|
|
|
|
2005-09-09 08:15:47 +00:00
|
|
|
|
|
|
|
OPTIONS
|
|
|
|
-------
|
2005-11-07 05:30:56 +00:00
|
|
|
include::merge-options.txt[]
|
2005-09-09 08:15:47 +00:00
|
|
|
|
2007-10-30 18:54:11 +00:00
|
|
|
-m <msg>::
|
2009-10-09 10:16:15 +00:00
|
|
|
Set the commit message to be used for the merge commit (in
|
|
|
|
case one is created). The 'git fmt-merge-msg' command can be
|
|
|
|
used to give a good default for automated 'git merge'
|
|
|
|
invocations.
|
2005-11-01 20:45:55 +00:00
|
|
|
|
2009-12-04 08:20:48 +00:00
|
|
|
--rerere-autoupdate::
|
|
|
|
--no-rerere-autoupdate::
|
|
|
|
Allow the rerere mechanism to update the index with the
|
|
|
|
result of auto-conflict resolution if possible.
|
|
|
|
|
2008-07-30 09:33:43 +00:00
|
|
|
<remote>...::
|
|
|
|
Other branch heads to merge into our branch. You need at
|
2005-09-09 08:15:47 +00:00
|
|
|
least one <remote>. Specifying more than one <remote>
|
|
|
|
obviously means you are trying an Octopus.
|
|
|
|
|
2005-11-06 16:26:07 +00:00
|
|
|
include::merge-strategies.txt[]
|
|
|
|
|
2005-09-09 08:15:47 +00:00
|
|
|
|
2009-03-26 09:39:04 +00:00
|
|
|
If you tried a merge which resulted in complex conflicts and
|
2009-03-25 18:23:42 +00:00
|
|
|
want to start over, you can recover with 'git-reset'.
|
2005-12-17 02:23:33 +00:00
|
|
|
|
2007-07-12 23:54:06 +00:00
|
|
|
CONFIGURATION
|
|
|
|
-------------
|
2008-04-06 01:23:42 +00:00
|
|
|
include::merge-config.txt[]
|
2007-07-12 23:54:06 +00:00
|
|
|
|
2007-09-23 22:51:43 +00:00
|
|
|
branch.<name>.mergeoptions::
|
|
|
|
Sets default options for merging into branch <name>. The syntax and
|
2009-10-09 18:51:14 +00:00
|
|
|
supported options are the same as those of 'git merge', but option
|
|
|
|
values containing whitespace characters are currently not supported.
|
2005-12-17 02:23:33 +00:00
|
|
|
|
2005-11-29 06:54:30 +00:00
|
|
|
HOW MERGE WORKS
|
|
|
|
---------------
|
|
|
|
|
|
|
|
A merge is always between the current `HEAD` and one or more
|
2008-03-03 17:52:49 +00:00
|
|
|
commits (usually, branch head or tag), and the index file must
|
2008-07-19 18:17:22 +00:00
|
|
|
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
|
2008-12-09 06:23:51 +00:00
|
|
|
most common case especially when invoked from 'git pull':
|
|
|
|
you are tracking an upstream repository, have committed no local
|
2008-07-19 18:17:22 +00:00
|
|
|
changes and now you want to update to a newer upstream revision.
|
2008-12-09 06:23:51 +00:00
|
|
|
Your `HEAD` (and the index) is updated to point at the merged
|
2008-07-19 18:17:22 +00:00
|
|
|
commit, without creating an extra merge commit. This is
|
|
|
|
called "Fast-forward".
|
|
|
|
|
|
|
|
* Both the merged commit and `HEAD` are independent and must be
|
2008-12-09 06:23:51 +00:00
|
|
|
tied together by a merge commit that has both of them as its parents.
|
2008-07-19 18:17:22 +00:00
|
|
|
The rest of this section describes this "True merge" case.
|
|
|
|
|
|
|
|
The chosen merge strategy merges the two commits into a single
|
|
|
|
new source tree.
|
2008-12-09 06:23:51 +00:00
|
|
|
When things merge cleanly, this is what happens:
|
2005-11-29 06:54:30 +00:00
|
|
|
|
2007-08-01 15:43:06 +00:00
|
|
|
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.
|
2005-11-29 06:54:30 +00:00
|
|
|
|
|
|
|
Because of 2., we require that the original state of the index
|
2008-12-09 06:23:51 +00:00
|
|
|
file matches exactly the current `HEAD` commit; otherwise we
|
2005-11-29 06:54:30 +00:00
|
|
|
will write out your local changes already registered in your
|
|
|
|
index file along with the merge result, which is not good.
|
2008-12-09 06:23:51 +00:00
|
|
|
Because 1. involves only those paths differing between your
|
2005-11-29 06:54:30 +00:00
|
|
|
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.
|
|
|
|
|
2008-12-09 06:23:51 +00:00
|
|
|
When there are conflicts, the following happens:
|
2005-11-29 06:54:30 +00:00
|
|
|
|
|
|
|
1. `HEAD` stays the same.
|
|
|
|
|
|
|
|
2. Cleanly merged paths are updated both in the index file and
|
|
|
|
in your working tree.
|
|
|
|
|
2005-12-02 09:05:35 +00:00
|
|
|
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
|
2008-06-30 06:09:04 +00:00
|
|
|
can inspect the stages with `git ls-files -u`). The working
|
2008-12-09 06:23:51 +00:00
|
|
|
tree files contain the result of the "merge" program; i.e. 3-way
|
|
|
|
merge results with familiar conflict markers `<<< === >>>`.
|
2005-11-29 06:54:30 +00:00
|
|
|
|
|
|
|
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`.
|
|
|
|
|
2008-09-01 03:36:32 +00:00
|
|
|
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.
|
|
|
|
------------
|
|
|
|
|
2008-12-09 06:23:51 +00:00
|
|
|
The area where a pair of conflicting changes happened is marked with markers
|
2009-03-15 11:30:52 +00:00
|
|
|
`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
|
2008-12-09 06:23:51 +00:00
|
|
|
is typically your side, and the part afterwards is typically their side.
|
2008-09-01 03:36:32 +00:00
|
|
|
|
2008-12-09 06:23:51 +00:00
|
|
|
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
|
2008-09-01 03:36:32 +00:00
|
|
|
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.
|
|
|
|
------------
|
|
|
|
|
2009-03-15 11:30:52 +00:00
|
|
|
In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
|
|
|
|
another `|||||||` marker that is followed by the original text. You can
|
2008-09-01 03:36:32 +00:00
|
|
|
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
|
|
|
|
------------------------
|
|
|
|
|
2005-11-29 06:54:30 +00:00
|
|
|
After seeing a conflict, you can do two things:
|
|
|
|
|
2008-12-09 06:23:51 +00:00
|
|
|
* Decide not to merge. The only clean-ups you need are to reset
|
2005-11-29 06:54:30 +00:00
|
|
|
the index file to the `HEAD` commit to reverse 2. and to clean
|
2008-07-19 18:17:22 +00:00
|
|
|
up working tree changes made by 2. and 3.; 'git-reset --hard' can
|
2005-11-29 06:54:30 +00:00
|
|
|
be used for this.
|
|
|
|
|
2008-08-22 03:32:00 +00:00
|
|
|
* Resolve the conflicts. Git will mark the conflicts in
|
|
|
|
the working tree. Edit the files into shape and
|
2008-12-09 06:23:51 +00:00
|
|
|
'git-add' them to the index. Use 'git-commit' to seal the deal.
|
2005-11-29 06:54:30 +00:00
|
|
|
|
2008-08-22 03:32:00 +00:00
|
|
|
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.
|
2005-11-29 06:54:30 +00:00
|
|
|
|
2009-10-21 17:21:23 +00:00
|
|
|
|
|
|
|
EXAMPLES
|
|
|
|
--------
|
|
|
|
|
|
|
|
* Merge branches `fixes` and `enhancements` on top of
|
|
|
|
the current branch, making an octopus merge:
|
|
|
|
+
|
|
|
|
------------------------------------------------
|
|
|
|
$ git merge fixes enhancements
|
|
|
|
------------------------------------------------
|
|
|
|
|
|
|
|
* Merge branch `obsolete` into the current branch, using `ours`
|
|
|
|
merge strategy:
|
|
|
|
+
|
|
|
|
------------------------------------------------
|
|
|
|
$ git merge -s ours obsolete
|
|
|
|
------------------------------------------------
|
|
|
|
|
|
|
|
* Merge branch `maint` into the current branch, but do not make
|
|
|
|
a new commit automatically:
|
|
|
|
+
|
|
|
|
------------------------------------------------
|
|
|
|
$ git merge --no-commit maint
|
|
|
|
------------------------------------------------
|
|
|
|
+
|
|
|
|
This can be used when you want to include further changes to the
|
|
|
|
merge, or want to write your own merge commit message.
|
|
|
|
+
|
|
|
|
You should refrain from abusing this option to sneak substantial
|
|
|
|
changes into a merge commit. Small fixups like bumping
|
|
|
|
release/version name would be acceptable.
|
|
|
|
|
|
|
|
|
2005-11-01 20:45:55 +00:00
|
|
|
SEE ALSO
|
|
|
|
--------
|
2007-12-29 06:20:38 +00:00
|
|
|
linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
|
2008-06-30 18:56:34 +00:00
|
|
|
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]
|
2005-11-01 20:45:55 +00:00
|
|
|
|
2005-09-09 08:15:47 +00:00
|
|
|
Author
|
|
|
|
------
|
2008-07-21 19:14:42 +00:00
|
|
|
Written by Junio C Hamano <gitster@pobox.com>
|
2005-09-09 08:15:47 +00:00
|
|
|
|
|
|
|
|
|
|
|
Documentation
|
|
|
|
--------------
|
|
|
|
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
|
|
|
|
|
|
|
|
GIT
|
|
|
|
---
|
2008-06-06 07:07:32 +00:00
|
|
|
Part of the linkgit:git[1] suite
|