Post 2.3 cycle (batch #9)
[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]
e703d711 13 [-s <strategy>] [-X <strategy-option>] [-S[<key-id>]]
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
76b80cdf
MM
59*Warning*: Running 'git merge' with non-trivial uncommitted changes is
60discouraged: while possible, it may leave you in a state that is hard to
e330d8ca 61back out of in the case of a conflict.
dee48c3c 62
0f69be53
JH
63
64OPTIONS
65-------
93d69d86 66include::merge-options.txt[]
0f69be53 67
5f737ac9
NV
68-S[<keyid>]::
69--gpg-sign[=<keyid>]::
70 GPG-sign the resulting merge commit.
71
dee48c3c 72-m <msg>::
0f8a02c6 73 Set the commit message to be used for the merge commit (in
f0ecac2b 74 case one is created).
af77aee9
NP
75+
76If `--log` is specified, a shortlog of the commits being merged
77will be appended to the specified message.
78+
79The 'git fmt-merge-msg' command can be
80used to give a good default for automated 'git merge'
81invocations.
3c64314c 82
0460ed2c 83--[no-]rerere-autoupdate::
cb6020bb
JH
84 Allow the rerere mechanism to update the index with the
85 result of auto-conflict resolution if possible.
86
35d2fffd
JH
87--abort::
88 Abort the current conflict resolution process, and
89 try to reconstruct the pre-merge state.
90+
91If there were uncommitted worktree changes present when the merge
92started, 'git merge --abort' will in some cases be unable to
93reconstruct these changes. It is therefore recommended to always
94commit or stash your changes before running 'git merge'.
95+
96'git merge --abort' is equivalent to 'git reset --merge' when
97`MERGE_HEAD` is present.
98
57bddb11
TR
99<commit>...::
100 Commits, usually other branch heads, to merge into our branch.
93e535a5
JH
101 Specifying more than one commit will create a merge with
102 more than two parents (affectionately called an Octopus merge).
103+
a01f7f2b
FC
104If no commit is given from the command line, merge the remote-tracking
105branches that the current branch is configured to use as its upstream.
93e535a5 106See also the configuration section of this manual page.
0f69be53 107
bb73d73c 108
30f2bade
JN
109PRE-MERGE CHECKS
110----------------
0f69be53 111
30f2bade
JN
112Before applying outside changes, you should get your own work in
113good shape and committed locally, so it will not be clobbered if
114there are conflicts. See also linkgit:git-stash[1].
115'git pull' and 'git merge' will stop without doing anything when
116local uncommitted changes overlap with files that 'git pull'/'git
117merge' may need to update.
3ae854c3 118
30f2bade
JN
119To avoid recording unrelated changes in the merge commit,
120'git pull' and 'git merge' will also abort if there are any changes
121registered in the index relative to the `HEAD` commit. (One
122exception is when the changed index entries are in the state that
123would result from the merge already.)
dbddb714 124
30f2bade
JN
125If all named commits are already ancestors of `HEAD`, 'git merge'
126will exit early with the message "Already up-to-date."
3ae854c3 127
29280311
JN
128FAST-FORWARD MERGE
129------------------
130
131Often the current branch head is an ancestor of the named commit.
132This is the most common case especially when invoked from 'git
133pull': you are tracking an upstream repository, you have committed
134no local changes, and now you want to update to a newer upstream
135revision. In this case, a new commit is not needed to store the
136combined history; instead, the `HEAD` (along with the index) is
137updated to point at the named commit, without creating an extra
138merge commit.
139
140This behavior can be suppressed with the `--no-ff` option.
ffb1a4be 141
ebef7e50
JN
142TRUE MERGE
143----------
c0be8aa0 144
29280311
JN
145Except in a fast-forward merge (see above), the branches to be
146merged must be tied together by a merge commit that has both of them
147as its parents.
ffb1a4be 148
ebef7e50
JN
149A merged version reconciling the changes from all branches to be
150merged is committed, and your `HEAD`, index, and working tree are
151updated to it. It is possible to have modifications in the working
152tree as long as they do not overlap; the update will preserve them.
ffb1a4be 153
ebef7e50
JN
154When it is not obvious how to reconcile the changes, the following
155happens:
ffb1a4be 156
ebef7e50
JN
1571. The `HEAD` pointer stays the same.
1582. The `MERGE_HEAD` ref is set to point to the other branch head.
1593. Paths that merged cleanly are updated both in the index file and
ffb1a4be 160 in your working tree.
ebef7e50
JN
1614. For conflicting paths, the index file records up to three
162 versions: stage 1 stores the version from the common ancestor,
163 stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
b1889c36 164 can inspect the stages with `git ls-files -u`). The working
29b802aa 165 tree files contain the result of the "merge" program; i.e. 3-way
ebef7e50
JN
166 merge results with familiar conflict markers `<<<` `===` `>>>`.
1675. No other changes are made. In particular, the local
ffb1a4be
JH
168 modifications you had before you started merge will stay the
169 same and the index entries for them stay as they were,
170 i.e. matching `HEAD`.
171
ed4a6baa 172If you tried a merge which resulted in complex conflicts and
35d2fffd 173want to start over, you can recover with `git merge --abort`.
ed4a6baa 174
77c72780
JH
175MERGING TAG
176-----------
177
178When merging an annotated (and possibly signed) tag, Git always
179creates a merge commit even if a fast-forward merge is possible, and
180the commit message template is prepared with the tag message.
181Additionally, if the tag is signed, the signature check is reported
182as a comment in the message template. See also linkgit:git-tag[1].
183
184When you want to just integrate with the work leading to the commit
185that happens to be tagged, e.g. synchronizing with an upstream
186release point, you may not want to make an unnecessary merge commit.
187
188In such a case, you can "unwrap" the tag yourself before feeding it
189to `git merge`, or pass `--ff-only` when you do not have any work on
190your own. e.g.
191
e45bda87 192----
77c72780
JH
193git fetch origin
194git merge v1.2.3^0
195git merge --ff-only v1.2.3
e45bda87 196----
77c72780
JH
197
198
70a3f897
JH
199HOW CONFLICTS ARE PRESENTED
200---------------------------
201
202During a merge, the working tree files are updated to reflect the result
203of the merge. Among the changes made to the common ancestor's version,
204non-overlapping ones (that is, you changed an area of the file while the
205other side left that area intact, or vice versa) are incorporated in the
206final result verbatim. When both sides made changes to the same area,
2de9b711 207however, Git cannot randomly pick one side over the other, and asks you to
70a3f897
JH
208resolve it by leaving what both sides did to that area.
209
2de9b711 210By default, Git uses the same style as the one used by the "merge" program
70a3f897
JH
211from the RCS suite to present such a conflicted hunk, 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=======
220Git makes conflict resolution easy.
221>>>>>>> theirs:sample.txt
222And here is another line that is cleanly resolved or unmodified.
223------------
224
29b802aa 225The area where a pair of conflicting changes happened is marked with markers
dcb11263 226`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
29b802aa 227is typically your side, and the part afterwards is typically their side.
70a3f897 228
29b802aa
RW
229The default format does not show what the original said in the conflicting
230area. You cannot tell how many lines are deleted and replaced with
231Barbie's remark on your side. The only thing you can tell is that your
70a3f897
JH
232side wants to say it is hard and you'd prefer to go shopping, while the
233other side wants to claim it is easy.
234
235An alternative style can be used by setting the "merge.conflictstyle"
236configuration variable to "diff3". In "diff3" style, the above conflict
237may look like this:
238
239------------
240Here are lines that are either unchanged from the common
241ancestor, or cleanly resolved because only one side changed.
242<<<<<<< yours:sample.txt
243Conflict resolution is hard;
244let's go shopping.
245|||||||
246Conflict resolution is hard.
247=======
248Git makes conflict resolution easy.
249>>>>>>> theirs:sample.txt
250And here is another line that is cleanly resolved or unmodified.
251------------
252
dcb11263
CJ
253In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
254another `|||||||` marker that is followed by the original text. You can
70a3f897
JH
255tell that the original just stated a fact, and your side simply gave in to
256that statement and gave up, while the other side tried to have a more
257positive attitude. You can sometimes come up with a better resolution by
258viewing the original.
259
260
261HOW TO RESOLVE CONFLICTS
262------------------------
263
ffb1a4be
JH
264After seeing a conflict, you can do two things:
265
29b802aa 266 * Decide not to merge. The only clean-ups you need are to reset
ffb1a4be 267 the index file to the `HEAD` commit to reverse 2. and to clean
35d2fffd
JH
268 up working tree changes made by 2. and 3.; `git merge --abort`
269 can be used for this.
ffb1a4be 270
34ad1afa
DH
271 * Resolve the conflicts. Git will mark the conflicts in
272 the working tree. Edit the files into shape and
0b444cdb 273 'git add' them to the index. Use 'git commit' to seal the deal.
ffb1a4be 274
34ad1afa
DH
275You can work through the conflict with a number of tools:
276
ca768288 277 * Use a mergetool. `git mergetool` to launch a graphical
34ad1afa
DH
278 mergetool which will work you through the merge.
279
ca768288 280 * Look at the diffs. `git diff` will show a three-way diff,
3588cf94
JN
281 highlighting changes from both the `HEAD` and `MERGE_HEAD`
282 versions.
34ad1afa 283
3588cf94
JN
284 * Look at the diffs from each branch. `git log --merge -p <path>`
285 will show diffs first for the `HEAD` version and then the
286 `MERGE_HEAD` version.
34ad1afa 287
ca768288 288 * Look at the originals. `git show :1:filename` shows the
3588cf94
JN
289 common ancestor, `git show :2:filename` shows the `HEAD`
290 version, and `git show :3:filename` shows the `MERGE_HEAD`
291 version.
ffb1a4be 292
d504f697
CB
293
294EXAMPLES
295--------
296
297* Merge branches `fixes` and `enhancements` on top of
298 the current branch, making an octopus merge:
299+
300------------------------------------------------
301$ git merge fixes enhancements
302------------------------------------------------
303
304* Merge branch `obsolete` into the current branch, using `ours`
305 merge strategy:
306+
307------------------------------------------------
308$ git merge -s ours obsolete
309------------------------------------------------
310
311* Merge branch `maint` into the current branch, but do not make
312 a new commit automatically:
313+
314------------------------------------------------
315$ git merge --no-commit maint
316------------------------------------------------
317+
318This can be used when you want to include further changes to the
319merge, or want to write your own merge commit message.
320+
321You should refrain from abusing this option to sneak substantial
322changes into a merge commit. Small fixups like bumping
323release/version name would be acceptable.
324
325
a4081bac
JN
326include::merge-strategies.txt[]
327
35e9d630
JN
328CONFIGURATION
329-------------
330include::merge-config.txt[]
331
332branch.<name>.mergeoptions::
333 Sets default options for merging into branch <name>. The syntax and
334 supported options are the same as those of 'git merge', but option
335 values containing whitespace characters are currently not supported.
336
3c64314c
PB
337SEE ALSO
338--------
5162e697 339linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
483bc4f0
JN
340linkgit:gitattributes[5],
341linkgit:git-reset[1],
342linkgit:git-diff[1], linkgit:git-ls-files[1],
343linkgit:git-add[1], linkgit:git-rm[1],
344linkgit:git-mergetool[1]
3c64314c 345
0f69be53
JH
346GIT
347---
9e1f0a85 348Part of the linkgit:git[1] suite