Documentation: emphasize when git merge terminates early
[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
ffb1a4be
JH
89HOW MERGE WORKS
90---------------
91
92A merge is always between the current `HEAD` and one or more
30f2bade 93commits (usually a branch head or tag).
c0be8aa0 94
30f2bade 95Two kinds of merge can happen:
c0be8aa0
PB
96
97* `HEAD` is already contained in the merged commit. This is the
29b802aa
RW
98 most common case especially when invoked from 'git pull':
99 you are tracking an upstream repository, have committed no local
c0be8aa0 100 changes and now you want to update to a newer upstream revision.
29b802aa 101 Your `HEAD` (and the index) is updated to point at the merged
c0be8aa0
PB
102 commit, without creating an extra merge commit. This is
103 called "Fast-forward".
104
105* Both the merged commit and `HEAD` are independent and must be
29b802aa 106 tied together by a merge commit that has both of them as its parents.
c0be8aa0
PB
107 The rest of this section describes this "True merge" case.
108
109The chosen merge strategy merges the two commits into a single
110new source tree.
29b802aa 111When things merge cleanly, this is what happens:
ffb1a4be 112
434e6ef8
SH
1131. The results are updated both in the index file and in your
114 working tree;
1152. Index file is written out as a tree;
1163. The tree gets committed; and
1174. The `HEAD` pointer gets advanced.
ffb1a4be
JH
118
119Because of 2., we require that the original state of the index
29b802aa 120file matches exactly the current `HEAD` commit; otherwise we
ffb1a4be
JH
121will write out your local changes already registered in your
122index file along with the merge result, which is not good.
29b802aa 123Because 1. involves only those paths differing between your
57bddb11
TR
124branch and the branch you are merging
125(which is typically a fraction of the whole tree), you can
ffb1a4be
JH
126have local modifications in your working tree as long as they do
127not overlap with what the merge updates.
128
29b802aa 129When there are conflicts, the following happens:
ffb1a4be
JH
130
1311. `HEAD` stays the same.
132
1332. Cleanly merged paths are updated both in the index file and
134 in your working tree.
135
3ace1fe3
JH
1363. For conflicting paths, the index file records up to three
137 versions; stage1 stores the version from the common ancestor,
57bddb11 138 stage2 from `HEAD`, and stage3 from the other branch (you
b1889c36 139 can inspect the stages with `git ls-files -u`). The working
29b802aa
RW
140 tree files contain the result of the "merge" program; i.e. 3-way
141 merge results with familiar conflict markers `<<< === >>>`.
ffb1a4be
JH
142
1434. No other changes are done. In particular, the local
144 modifications you had before you started merge will stay the
145 same and the index entries for them stay as they were,
146 i.e. matching `HEAD`.
147
ed4a6baa
JN
148If you tried a merge which resulted in complex conflicts and
149want to start over, you can recover with `git reset --merge`.
150
70a3f897
JH
151HOW CONFLICTS ARE PRESENTED
152---------------------------
153
154During a merge, the working tree files are updated to reflect the result
155of the merge. Among the changes made to the common ancestor's version,
156non-overlapping ones (that is, you changed an area of the file while the
157other side left that area intact, or vice versa) are incorporated in the
158final result verbatim. When both sides made changes to the same area,
159however, git cannot randomly pick one side over the other, and asks you to
160resolve it by leaving what both sides did to that area.
161
162By default, git uses the same style as that is used by "merge" program
163from the RCS suite to present such a conflicted hunk, like this:
164
165------------
166Here are lines that are either unchanged from the common
167ancestor, or cleanly resolved because only one side changed.
168<<<<<<< yours:sample.txt
169Conflict resolution is hard;
170let's go shopping.
171=======
172Git makes conflict resolution easy.
173>>>>>>> theirs:sample.txt
174And here is another line that is cleanly resolved or unmodified.
175------------
176
29b802aa 177The area where a pair of conflicting changes happened is marked with markers
dcb11263 178`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
29b802aa 179is typically your side, and the part afterwards is typically their side.
70a3f897 180
29b802aa
RW
181The default format does not show what the original said in the conflicting
182area. You cannot tell how many lines are deleted and replaced with
183Barbie's remark on your side. The only thing you can tell is that your
70a3f897
JH
184side wants to say it is hard and you'd prefer to go shopping, while the
185other side wants to claim it is easy.
186
187An alternative style can be used by setting the "merge.conflictstyle"
188configuration variable to "diff3". In "diff3" style, the above conflict
189may look like this:
190
191------------
192Here are lines that are either unchanged from the common
193ancestor, or cleanly resolved because only one side changed.
194<<<<<<< yours:sample.txt
195Conflict resolution is hard;
196let's go shopping.
197|||||||
198Conflict resolution is hard.
199=======
200Git makes conflict resolution easy.
201>>>>>>> theirs:sample.txt
202And here is another line that is cleanly resolved or unmodified.
203------------
204
dcb11263
CJ
205In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
206another `|||||||` marker that is followed by the original text. You can
70a3f897
JH
207tell that the original just stated a fact, and your side simply gave in to
208that statement and gave up, while the other side tried to have a more
209positive attitude. You can sometimes come up with a better resolution by
210viewing the original.
211
212
213HOW TO RESOLVE CONFLICTS
214------------------------
215
ffb1a4be
JH
216After seeing a conflict, you can do two things:
217
29b802aa 218 * Decide not to merge. The only clean-ups you need are to reset
ffb1a4be 219 the index file to the `HEAD` commit to reverse 2. and to clean
ca768288 220 up working tree changes made by 2. and 3.; `git-reset --hard` can
ffb1a4be
JH
221 be used for this.
222
34ad1afa
DH
223 * Resolve the conflicts. Git will mark the conflicts in
224 the working tree. Edit the files into shape and
0b444cdb 225 'git add' them to the index. Use 'git commit' to seal the deal.
ffb1a4be 226
34ad1afa
DH
227You can work through the conflict with a number of tools:
228
ca768288 229 * Use a mergetool. `git mergetool` to launch a graphical
34ad1afa
DH
230 mergetool which will work you through the merge.
231
ca768288 232 * Look at the diffs. `git diff` will show a three-way diff,
57bddb11 233 highlighting changes from both the HEAD and their versions.
34ad1afa 234
ca768288 235 * Look at the diffs on their own. `git log --merge -p <path>`
57bddb11
TR
236 will show diffs first for the HEAD version and then
237 their version.
34ad1afa 238
ca768288
TR
239 * Look at the originals. `git show :1:filename` shows the
240 common ancestor, `git show :2:filename` shows the HEAD
241 version and `git show :3:filename` shows their version.
ffb1a4be 242
d504f697
CB
243
244EXAMPLES
245--------
246
247* Merge branches `fixes` and `enhancements` on top of
248 the current branch, making an octopus merge:
249+
250------------------------------------------------
251$ git merge fixes enhancements
252------------------------------------------------
253
254* Merge branch `obsolete` into the current branch, using `ours`
255 merge strategy:
256+
257------------------------------------------------
258$ git merge -s ours obsolete
259------------------------------------------------
260
261* Merge branch `maint` into the current branch, but do not make
262 a new commit automatically:
263+
264------------------------------------------------
265$ git merge --no-commit maint
266------------------------------------------------
267+
268This can be used when you want to include further changes to the
269merge, or want to write your own merge commit message.
270+
271You should refrain from abusing this option to sneak substantial
272changes into a merge commit. Small fixups like bumping
273release/version name would be acceptable.
274
275
a4081bac
JN
276include::merge-strategies.txt[]
277
35e9d630
JN
278CONFIGURATION
279-------------
280include::merge-config.txt[]
281
282branch.<name>.mergeoptions::
283 Sets default options for merging into branch <name>. The syntax and
284 supported options are the same as those of 'git merge', but option
285 values containing whitespace characters are currently not supported.
286
3c64314c
PB
287SEE ALSO
288--------
5162e697 289linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
483bc4f0
JN
290linkgit:gitattributes[5],
291linkgit:git-reset[1],
292linkgit:git-diff[1], linkgit:git-ls-files[1],
293linkgit:git-add[1], linkgit:git-rm[1],
294linkgit:git-mergetool[1]
3c64314c 295
0f69be53
JH
296Author
297------
59eb68aa 298Written by Junio C Hamano <gitster@pobox.com>
0f69be53
JH
299
300
301Documentation
302--------------
303Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
304
305GIT
306---
9e1f0a85 307Part of the linkgit:git[1] suite