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