You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
299 lines
10 KiB
299 lines
10 KiB
git-merge(1) |
|
============ |
|
|
|
NAME |
|
---- |
|
git-merge - Join two or more development histories together |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... |
|
[--[no-]rerere-autoupdate] [-m <msg>] <commit>... |
|
'git merge' <msg> HEAD <commit>... |
|
|
|
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>...`. |
|
|
|
*Warning*: Running 'git merge' with uncommitted changes is |
|
discouraged: while possible, it leaves you in a state that is hard to |
|
back out of in the case of a conflict. |
|
|
|
|
|
OPTIONS |
|
------- |
|
include::merge-options.txt[] |
|
|
|
-m <msg>:: |
|
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. |
|
|
|
--rerere-autoupdate:: |
|
--no-rerere-autoupdate:: |
|
Allow the rerere mechanism to update the index with the |
|
result of auto-conflict resolution if possible. |
|
|
|
<commit>...:: |
|
Commits, usually other branch heads, to merge into our branch. |
|
You need at least one <commit>. Specifying more than one |
|
<commit> obviously means you are trying an Octopus. |
|
|
|
|
|
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 reset --merge`. |
|
|
|
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 `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] |
|
|
|
Author |
|
------ |
|
Written by Junio C Hamano <gitster@pobox.com> |
|
|
|
|
|
Documentation |
|
-------------- |
|
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|