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