fast-export: fix argument name in error messages
[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
77c72780
JH
173MERGING TAG
174-----------
175
176When merging an annotated (and possibly signed) tag, Git always
177creates a merge commit even if a fast-forward merge is possible, and
178the commit message template is prepared with the tag message.
179Additionally, if the tag is signed, the signature check is reported
180as a comment in the message template. See also linkgit:git-tag[1].
181
182When you want to just integrate with the work leading to the commit
183that happens to be tagged, e.g. synchronizing with an upstream
184release point, you may not want to make an unnecessary merge commit.
185
186In such a case, you can "unwrap" the tag yourself before feeding it
187to `git merge`, or pass `--ff-only` when you do not have any work on
188your own. e.g.
189
190---
191git fetch origin
192git merge v1.2.3^0
193git merge --ff-only v1.2.3
194---
195
196
70a3f897
JH
197HOW CONFLICTS ARE PRESENTED
198---------------------------
199
200During a merge, the working tree files are updated to reflect the result
201of the merge. Among the changes made to the common ancestor's version,
202non-overlapping ones (that is, you changed an area of the file while the
203other side left that area intact, or vice versa) are incorporated in the
204final result verbatim. When both sides made changes to the same area,
205however, git cannot randomly pick one side over the other, and asks you to
206resolve it by leaving what both sides did to that area.
207
edfbbf7e 208By default, git uses the same style as the one used by the "merge" program
70a3f897
JH
209from the RCS suite to present such a conflicted hunk, like this:
210
211------------
212Here are lines that are either unchanged from the common
213ancestor, or cleanly resolved because only one side changed.
214<<<<<<< yours:sample.txt
215Conflict resolution is hard;
216let's go shopping.
217=======
218Git makes conflict resolution easy.
219>>>>>>> theirs:sample.txt
220And here is another line that is cleanly resolved or unmodified.
221------------
222
29b802aa 223The area where a pair of conflicting changes happened is marked with markers
dcb11263 224`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
29b802aa 225is typically your side, and the part afterwards is typically their side.
70a3f897 226
29b802aa
RW
227The default format does not show what the original said in the conflicting
228area. You cannot tell how many lines are deleted and replaced with
229Barbie's remark on your side. The only thing you can tell is that your
70a3f897
JH
230side wants to say it is hard and you'd prefer to go shopping, while the
231other side wants to claim it is easy.
232
233An alternative style can be used by setting the "merge.conflictstyle"
234configuration variable to "diff3". In "diff3" style, the above conflict
235may look like this:
236
237------------
238Here are lines that are either unchanged from the common
239ancestor, or cleanly resolved because only one side changed.
240<<<<<<< yours:sample.txt
241Conflict resolution is hard;
242let's go shopping.
243|||||||
244Conflict resolution is hard.
245=======
246Git makes conflict resolution easy.
247>>>>>>> theirs:sample.txt
248And here is another line that is cleanly resolved or unmodified.
249------------
250
dcb11263
CJ
251In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
252another `|||||||` marker that is followed by the original text. You can
70a3f897
JH
253tell that the original just stated a fact, and your side simply gave in to
254that statement and gave up, while the other side tried to have a more
255positive attitude. You can sometimes come up with a better resolution by
256viewing the original.
257
258
259HOW TO RESOLVE CONFLICTS
260------------------------
261
ffb1a4be
JH
262After seeing a conflict, you can do two things:
263
29b802aa 264 * Decide not to merge. The only clean-ups you need are to reset
ffb1a4be 265 the index file to the `HEAD` commit to reverse 2. and to clean
35d2fffd
JH
266 up working tree changes made by 2. and 3.; `git merge --abort`
267 can be used for this.
ffb1a4be 268
34ad1afa
DH
269 * Resolve the conflicts. Git will mark the conflicts in
270 the working tree. Edit the files into shape and
0b444cdb 271 'git add' them to the index. Use 'git commit' to seal the deal.
ffb1a4be 272
34ad1afa
DH
273You can work through the conflict with a number of tools:
274
ca768288 275 * Use a mergetool. `git mergetool` to launch a graphical
34ad1afa
DH
276 mergetool which will work you through the merge.
277
ca768288 278 * Look at the diffs. `git diff` will show a three-way diff,
3588cf94
JN
279 highlighting changes from both the `HEAD` and `MERGE_HEAD`
280 versions.
34ad1afa 281
3588cf94
JN
282 * Look at the diffs from each branch. `git log --merge -p <path>`
283 will show diffs first for the `HEAD` version and then the
284 `MERGE_HEAD` version.
34ad1afa 285
ca768288 286 * Look at the originals. `git show :1:filename` shows the
3588cf94
JN
287 common ancestor, `git show :2:filename` shows the `HEAD`
288 version, and `git show :3:filename` shows the `MERGE_HEAD`
289 version.
ffb1a4be 290
d504f697
CB
291
292EXAMPLES
293--------
294
295* Merge branches `fixes` and `enhancements` on top of
296 the current branch, making an octopus merge:
297+
298------------------------------------------------
299$ git merge fixes enhancements
300------------------------------------------------
301
302* Merge branch `obsolete` into the current branch, using `ours`
303 merge strategy:
304+
305------------------------------------------------
306$ git merge -s ours obsolete
307------------------------------------------------
308
309* Merge branch `maint` into the current branch, but do not make
310 a new commit automatically:
311+
312------------------------------------------------
313$ git merge --no-commit maint
314------------------------------------------------
315+
316This can be used when you want to include further changes to the
317merge, or want to write your own merge commit message.
318+
319You should refrain from abusing this option to sneak substantial
320changes into a merge commit. Small fixups like bumping
321release/version name would be acceptable.
322
323
a4081bac
JN
324include::merge-strategies.txt[]
325
35e9d630
JN
326CONFIGURATION
327-------------
328include::merge-config.txt[]
329
330branch.<name>.mergeoptions::
331 Sets default options for merging into branch <name>. The syntax and
332 supported options are the same as those of 'git merge', but option
333 values containing whitespace characters are currently not supported.
334
3c64314c
PB
335SEE ALSO
336--------
5162e697 337linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
483bc4f0
JN
338linkgit:gitattributes[5],
339linkgit:git-reset[1],
340linkgit:git-diff[1], linkgit:git-ls-files[1],
341linkgit:git-add[1], linkgit:git-rm[1],
342linkgit:git-mergetool[1]
3c64314c 343
0f69be53
JH
344GIT
345---
9e1f0a85 346Part of the linkgit:git[1] suite