355 lines
12 KiB
Plaintext
355 lines
12 KiB
Plaintext
git-merge(1)
|
|
============
|
|
|
|
NAME
|
|
----
|
|
git-merge - Join two or more development histories together
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
|
|
[-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
|
|
[--[no-]rerere-autoupdate] [-m <msg>] [<commit>...]
|
|
'git merge' <msg> HEAD <commit>...
|
|
'git merge' --abort
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
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>...`.
|
|
|
|
The third syntax ("`git merge --abort`") can only be run after the
|
|
merge has resulted in conflicts. 'git merge --abort' will abort the
|
|
merge process and try to reconstruct the pre-merge state. However,
|
|
if there were uncommitted changes when the merge started (and
|
|
especially if those changes were further modified after the merge
|
|
was started), 'git merge --abort' will in some cases be unable to
|
|
reconstruct the original (pre-merge) changes. Therefore:
|
|
|
|
*Warning*: Running 'git merge' with non-trivial uncommitted changes is
|
|
discouraged: while possible, it may leave you in a state that is hard to
|
|
back out of in the case of a conflict.
|
|
|
|
|
|
OPTIONS
|
|
-------
|
|
include::merge-options.txt[]
|
|
|
|
-S[<keyid>]::
|
|
--gpg-sign[=<keyid>]::
|
|
GPG-sign the resulting merge commit. The `keyid` argument is
|
|
optional and defaults to the committer identity; if specified,
|
|
it must be stuck to the option without a space.
|
|
|
|
-m <msg>::
|
|
Set the commit message to be used for the merge commit (in
|
|
case one is created).
|
|
+
|
|
If `--log` is specified, a shortlog of the commits being merged
|
|
will be appended to the specified message.
|
|
+
|
|
The 'git fmt-merge-msg' command can be
|
|
used to give a good default for automated 'git merge'
|
|
invocations. The automated message can include the branch description.
|
|
|
|
--[no-]rerere-autoupdate::
|
|
Allow the rerere mechanism to update the index with the
|
|
result of auto-conflict resolution if possible.
|
|
|
|
--abort::
|
|
Abort the current conflict resolution process, and
|
|
try to reconstruct the pre-merge state.
|
|
+
|
|
If there were uncommitted worktree changes present when the merge
|
|
started, 'git merge --abort' will in some cases be unable to
|
|
reconstruct these changes. It is therefore recommended to always
|
|
commit or stash your changes before running 'git merge'.
|
|
+
|
|
'git merge --abort' is equivalent to 'git reset --merge' when
|
|
`MERGE_HEAD` is present.
|
|
|
|
<commit>...::
|
|
Commits, usually other branch heads, to merge into our branch.
|
|
Specifying more than one commit will create a merge with
|
|
more than two parents (affectionately called an Octopus merge).
|
|
+
|
|
If no commit is given from the command line, merge the remote-tracking
|
|
branches that the current branch is configured to use as its upstream.
|
|
See also the configuration section of this manual page.
|
|
+
|
|
When `FETCH_HEAD` (and no other commit) is specified, the branches
|
|
recorded in the `.git/FETCH_HEAD` file by the previous invocation
|
|
of `git fetch` for merging are merged to the current branch.
|
|
|
|
|
|
PRE-MERGE CHECKS
|
|
----------------
|
|
|
|
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.
|
|
|
|
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.)
|
|
|
|
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.
|
|
|
|
TRUE MERGE
|
|
----------
|
|
|
|
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.
|
|
|
|
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
|
|
happens:
|
|
|
|
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
|
|
in your working tree.
|
|
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 `<<<` `===` `>>>`.
|
|
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,
|
|
i.e. matching `HEAD`.
|
|
|
|
If you tried a merge which resulted in complex conflicts and
|
|
want to start over, you can recover with `git merge --abort`.
|
|
|
|
MERGING TAG
|
|
-----------
|
|
|
|
When merging an annotated (and possibly signed) tag, Git always
|
|
creates a merge commit even if a fast-forward merge is possible, and
|
|
the commit message template is prepared with the tag message.
|
|
Additionally, if the tag is signed, the signature check is reported
|
|
as a comment in the message template. See also linkgit:git-tag[1].
|
|
|
|
When you want to just integrate with the work leading to the commit
|
|
that happens to be tagged, e.g. synchronizing with an upstream
|
|
release point, you may not want to make an unnecessary merge commit.
|
|
|
|
In such a case, you can "unwrap" the tag yourself before feeding it
|
|
to `git merge`, or pass `--ff-only` when you do not have any work on
|
|
your own. e.g.
|
|
|
|
----
|
|
git fetch origin
|
|
git merge v1.2.3^0
|
|
git merge --ff-only v1.2.3
|
|
----
|
|
|
|
|
|
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 the one used by the "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 merge --abort`
|
|
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 `MERGE_HEAD`
|
|
versions.
|
|
|
|
* Look at the diffs from each branch. `git log --merge -p <path>`
|
|
will show diffs first for the `HEAD` version and then the
|
|
`MERGE_HEAD` 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 `MERGE_HEAD`
|
|
version.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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],
|
|
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]
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|