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