Documentation: simplify How Merge Works
[git/git.git] / Documentation / git-merge.txt
CommitLineData
0f69be53
JH
1git-merge(1)
2============
0f69be53
JH
3
4NAME
5----
c3f0baac 6git-merge - Join two or more development histories together
0f69be53
JH
7
8
9SYNOPSIS
10--------
17bcdad3 11[verse]
b1889c36 12'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
57bddb11
TR
13 [-m <msg>] <commit>...
14'git merge' <msg> HEAD <commit>...
0f69be53
JH
15
16DESCRIPTION
17-----------
b40bb374
JN
18Incorporates changes from the named commits (since the time their
19histories diverged from the current branch) into the current
20branch. This command is used by 'git pull' to incorporate changes
21from another repository and can be used by hand to merge changes
22from one branch into another.
23
24Assume the following history exists and the current branch is
25"`master`":
26
27------------
28 A---B---C topic
29 /
30 D---E---F---G master
31------------
32
33Then "`git merge topic`" will replay the changes made on the
34`topic` branch since it diverged from `master` (i.e., `E`) until
35its current commit (`C`) on top of `master`, and record the result
36in a new commit along with the names of the two parent commits and
37a log message from the user describing the changes.
38
39------------
40 A---B---C topic
41 / \
42 D---E---F---G---H master
43------------
0f69be53 44
57bddb11 45The second syntax (<msg> `HEAD` <commit>...) is supported for
dee48c3c 46historical reasons. Do not use it from the command line or in
57bddb11 47new scripts. It is the same as `git merge -m <msg> <commit>...`.
dee48c3c 48
0b444cdb 49*Warning*: Running 'git merge' with uncommitted changes is
e330d8ca
TR
50discouraged: while possible, it leaves you in a state that is hard to
51back out of in the case of a conflict.
52
0f69be53
JH
53
54OPTIONS
55-------
93d69d86 56include::merge-options.txt[]
0f69be53 57
dee48c3c 58-m <msg>::
0f8a02c6
JN
59 Set the commit message to be used for the merge commit (in
60 case one is created). The 'git fmt-merge-msg' command can be
61 used to give a good default for automated 'git merge'
62 invocations.
3c64314c 63
57bddb11
TR
64<commit>...::
65 Commits, usually other branch heads, to merge into our branch.
66 You need at least one <commit>. Specifying more than one
67 <commit> obviously means you are trying an Octopus.
0f69be53
JH
68
69
30f2bade
JN
70PRE-MERGE CHECKS
71----------------
72
73Before applying outside changes, you should get your own work in
74good shape and committed locally, so it will not be clobbered if
75there are conflicts. See also linkgit:git-stash[1].
76'git pull' and 'git merge' will stop without doing anything when
77local uncommitted changes overlap with files that 'git pull'/'git
78merge' may need to update.
79
80To avoid recording unrelated changes in the merge commit,
81'git pull' and 'git merge' will also abort if there are any changes
82registered in the index relative to the `HEAD` commit. (One
83exception is when the changed index entries are in the state that
84would result from the merge already.)
85
86If all named commits are already ancestors of `HEAD`, 'git merge'
87will exit early with the message "Already up-to-date."
88
29280311
JN
89FAST-FORWARD MERGE
90------------------
91
92Often the current branch head is an ancestor of the named commit.
93This is the most common case especially when invoked from 'git
94pull': you are tracking an upstream repository, you have committed
95no local changes, and now you want to update to a newer upstream
96revision. In this case, a new commit is not needed to store the
97combined history; instead, the `HEAD` (along with the index) is
98updated to point at the named commit, without creating an extra
99merge commit.
100
101This behavior can be suppressed with the `--no-ff` option.
102
ebef7e50
JN
103TRUE MERGE
104----------
c0be8aa0 105
29280311
JN
106Except in a fast-forward merge (see above), the branches to be
107merged must be tied together by a merge commit that has both of them
108as its parents.
ffb1a4be 109
ebef7e50
JN
110A merged version reconciling the changes from all branches to be
111merged is committed, and your `HEAD`, index, and working tree are
112updated to it. It is possible to have modifications in the working
113tree as long as they do not overlap; the update will preserve them.
ffb1a4be 114
ebef7e50
JN
115When it is not obvious how to reconcile the changes, the following
116happens:
ffb1a4be 117
ebef7e50
JN
1181. The `HEAD` pointer stays the same.
1192. The `MERGE_HEAD` ref is set to point to the other branch head.
1203. Paths that merged cleanly are updated both in the index file and
ffb1a4be 121 in your working tree.
ebef7e50
JN
1224. For conflicting paths, the index file records up to three
123 versions: stage 1 stores the version from the common ancestor,
124 stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
b1889c36 125 can inspect the stages with `git ls-files -u`). The working
29b802aa 126 tree files contain the result of the "merge" program; i.e. 3-way
ebef7e50
JN
127 merge results with familiar conflict markers `<<<` `===` `>>>`.
1285. No other changes are made. In particular, the local
ffb1a4be
JH
129 modifications you had before you started merge will stay the
130 same and the index entries for them stay as they were,
131 i.e. matching `HEAD`.
132
ed4a6baa
JN
133If you tried a merge which resulted in complex conflicts and
134want to start over, you can recover with `git reset --merge`.
135
70a3f897
JH
136HOW CONFLICTS ARE PRESENTED
137---------------------------
138
139During a merge, the working tree files are updated to reflect the result
140of the merge. Among the changes made to the common ancestor's version,
141non-overlapping ones (that is, you changed an area of the file while the
142other side left that area intact, or vice versa) are incorporated in the
143final result verbatim. When both sides made changes to the same area,
144however, git cannot randomly pick one side over the other, and asks you to
145resolve it by leaving what both sides did to that area.
146
147By default, git uses the same style as that is used by "merge" program
148from the RCS suite to present such a conflicted hunk, like this:
149
150------------
151Here are lines that are either unchanged from the common
152ancestor, or cleanly resolved because only one side changed.
153<<<<<<< yours:sample.txt
154Conflict resolution is hard;
155let's go shopping.
156=======
157Git makes conflict resolution easy.
158>>>>>>> theirs:sample.txt
159And here is another line that is cleanly resolved or unmodified.
160------------
161
29b802aa 162The area where a pair of conflicting changes happened is marked with markers
dcb11263 163`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
29b802aa 164is typically your side, and the part afterwards is typically their side.
70a3f897 165
29b802aa
RW
166The default format does not show what the original said in the conflicting
167area. You cannot tell how many lines are deleted and replaced with
168Barbie's remark on your side. The only thing you can tell is that your
70a3f897
JH
169side wants to say it is hard and you'd prefer to go shopping, while the
170other side wants to claim it is easy.
171
172An alternative style can be used by setting the "merge.conflictstyle"
173configuration variable to "diff3". In "diff3" style, the above conflict
174may look like this:
175
176------------
177Here are lines that are either unchanged from the common
178ancestor, or cleanly resolved because only one side changed.
179<<<<<<< yours:sample.txt
180Conflict resolution is hard;
181let's go shopping.
182|||||||
183Conflict resolution is hard.
184=======
185Git makes conflict resolution easy.
186>>>>>>> theirs:sample.txt
187And here is another line that is cleanly resolved or unmodified.
188------------
189
dcb11263
CJ
190In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
191another `|||||||` marker that is followed by the original text. You can
70a3f897
JH
192tell that the original just stated a fact, and your side simply gave in to
193that statement and gave up, while the other side tried to have a more
194positive attitude. You can sometimes come up with a better resolution by
195viewing the original.
196
197
198HOW TO RESOLVE CONFLICTS
199------------------------
200
ffb1a4be
JH
201After seeing a conflict, you can do two things:
202
29b802aa 203 * Decide not to merge. The only clean-ups you need are to reset
ffb1a4be 204 the index file to the `HEAD` commit to reverse 2. and to clean
ca768288 205 up working tree changes made by 2. and 3.; `git-reset --hard` can
ffb1a4be
JH
206 be used for this.
207
34ad1afa
DH
208 * Resolve the conflicts. Git will mark the conflicts in
209 the working tree. Edit the files into shape and
0b444cdb 210 'git add' them to the index. Use 'git commit' to seal the deal.
ffb1a4be 211
34ad1afa
DH
212You can work through the conflict with a number of tools:
213
ca768288 214 * Use a mergetool. `git mergetool` to launch a graphical
34ad1afa
DH
215 mergetool which will work you through the merge.
216
ca768288 217 * Look at the diffs. `git diff` will show a three-way diff,
57bddb11 218 highlighting changes from both the HEAD and their versions.
34ad1afa 219
ca768288 220 * Look at the diffs on their own. `git log --merge -p <path>`
57bddb11
TR
221 will show diffs first for the HEAD version and then
222 their version.
34ad1afa 223
ca768288
TR
224 * Look at the originals. `git show :1:filename` shows the
225 common ancestor, `git show :2:filename` shows the HEAD
226 version and `git show :3:filename` shows their version.
ffb1a4be 227
d504f697
CB
228
229EXAMPLES
230--------
231
232* Merge branches `fixes` and `enhancements` on top of
233 the current branch, making an octopus merge:
234+
235------------------------------------------------
236$ git merge fixes enhancements
237------------------------------------------------
238
239* Merge branch `obsolete` into the current branch, using `ours`
240 merge strategy:
241+
242------------------------------------------------
243$ git merge -s ours obsolete
244------------------------------------------------
245
246* Merge branch `maint` into the current branch, but do not make
247 a new commit automatically:
248+
249------------------------------------------------
250$ git merge --no-commit maint
251------------------------------------------------
252+
253This can be used when you want to include further changes to the
254merge, or want to write your own merge commit message.
255+
256You should refrain from abusing this option to sneak substantial
257changes into a merge commit. Small fixups like bumping
258release/version name would be acceptable.
259
260
a4081bac
JN
261include::merge-strategies.txt[]
262
35e9d630
JN
263CONFIGURATION
264-------------
265include::merge-config.txt[]
266
267branch.<name>.mergeoptions::
268 Sets default options for merging into branch <name>. The syntax and
269 supported options are the same as those of 'git merge', but option
270 values containing whitespace characters are currently not supported.
271
3c64314c
PB
272SEE ALSO
273--------
5162e697 274linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
483bc4f0
JN
275linkgit:gitattributes[5],
276linkgit:git-reset[1],
277linkgit:git-diff[1], linkgit:git-ls-files[1],
278linkgit:git-add[1], linkgit:git-rm[1],
279linkgit:git-mergetool[1]
3c64314c 280
0f69be53
JH
281Author
282------
59eb68aa 283Written by Junio C Hamano <gitster@pobox.com>
0f69be53
JH
284
285
286Documentation
287--------------
288Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
289
290GIT
291---
9e1f0a85 292Part of the linkgit:git[1] suite