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