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