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