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