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