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