]>
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] |
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>... |
0f69be53 JH |
16 | |
17 | DESCRIPTION | |
18 | ----------- | |
b40bb374 JN |
19 | Incorporates changes from the named commits (since the time their |
20 | histories diverged from the current branch) into the current | |
21 | branch. This command is used by 'git pull' to incorporate changes | |
22 | from another repository and can be used by hand to merge changes | |
23 | from one branch into another. | |
24 | ||
25 | Assume the following history exists and the current branch is | |
26 | "`master`": | |
27 | ||
28 | ------------ | |
29 | A---B---C topic | |
30 | / | |
31 | D---E---F---G master | |
32 | ------------ | |
33 | ||
34 | Then "`git merge topic`" will replay the changes made on the | |
35 | `topic` branch since it diverged from `master` (i.e., `E`) until | |
36 | its current commit (`C`) on top of `master`, and record the result | |
37 | in a new commit along with the names of the two parent commits and | |
38 | a log message from the user describing the changes. | |
39 | ||
40 | ------------ | |
41 | A---B---C topic | |
42 | / \ | |
43 | D---E---F---G---H master | |
44 | ------------ | |
0f69be53 | 45 | |
57bddb11 | 46 | The second syntax (<msg> `HEAD` <commit>...) is supported for |
dee48c3c | 47 | historical reasons. Do not use it from the command line or in |
57bddb11 | 48 | new scripts. It is the same as `git merge -m <msg> <commit>...`. |
dee48c3c | 49 | |
0b444cdb | 50 | *Warning*: Running 'git merge' with uncommitted changes is |
e330d8ca TR |
51 | discouraged: while possible, it leaves you in a state that is hard to |
52 | back out of in the case of a conflict. | |
dee48c3c | 53 | |
0f69be53 JH |
54 | |
55 | OPTIONS | |
56 | ------- | |
93d69d86 | 57 | include::merge-options.txt[] |
0f69be53 | 58 | |
dee48c3c | 59 | -m <msg>:: |
0f8a02c6 | 60 | Set the commit message to be used for the merge commit (in |
f0ecac2b TRC |
61 | case one is created). |
62 | ||
63 | If `--log` is specified, a shortlog of the commits being merged | |
64 | will be appended to the specified message. | |
65 | ||
66 | The 'git fmt-merge-msg' command can be | |
0f8a02c6 JN |
67 | used to give a good default for automated 'git merge' |
68 | invocations. | |
3c64314c | 69 | |
cb6020bb JH |
70 | --rerere-autoupdate:: |
71 | --no-rerere-autoupdate:: | |
72 | Allow the rerere mechanism to update the index with the | |
73 | result of auto-conflict resolution if possible. | |
74 | ||
57bddb11 TR |
75 | <commit>...:: |
76 | Commits, usually other branch heads, to merge into our branch. | |
77 | You need at least one <commit>. Specifying more than one | |
78 | <commit> obviously means you are trying an Octopus. | |
0f69be53 | 79 | |
bb73d73c | 80 | |
30f2bade JN |
81 | PRE-MERGE CHECKS |
82 | ---------------- | |
0f69be53 | 83 | |
30f2bade JN |
84 | Before applying outside changes, you should get your own work in |
85 | good shape and committed locally, so it will not be clobbered if | |
86 | there are conflicts. See also linkgit:git-stash[1]. | |
87 | 'git pull' and 'git merge' will stop without doing anything when | |
88 | local uncommitted changes overlap with files that 'git pull'/'git | |
89 | merge' may need to update. | |
3ae854c3 | 90 | |
30f2bade JN |
91 | To avoid recording unrelated changes in the merge commit, |
92 | 'git pull' and 'git merge' will also abort if there are any changes | |
93 | registered in the index relative to the `HEAD` commit. (One | |
94 | exception is when the changed index entries are in the state that | |
95 | would result from the merge already.) | |
dbddb714 | 96 | |
30f2bade JN |
97 | If all named commits are already ancestors of `HEAD`, 'git merge' |
98 | will exit early with the message "Already up-to-date." | |
3ae854c3 | 99 | |
29280311 JN |
100 | FAST-FORWARD MERGE |
101 | ------------------ | |
102 | ||
103 | Often the current branch head is an ancestor of the named commit. | |
104 | This is the most common case especially when invoked from 'git | |
105 | pull': you are tracking an upstream repository, you have committed | |
106 | no local changes, and now you want to update to a newer upstream | |
107 | revision. In this case, a new commit is not needed to store the | |
108 | combined history; instead, the `HEAD` (along with the index) is | |
109 | updated to point at the named commit, without creating an extra | |
110 | merge commit. | |
111 | ||
112 | This behavior can be suppressed with the `--no-ff` option. | |
ffb1a4be | 113 | |
ebef7e50 JN |
114 | TRUE MERGE |
115 | ---------- | |
c0be8aa0 | 116 | |
29280311 JN |
117 | Except in a fast-forward merge (see above), the branches to be |
118 | merged must be tied together by a merge commit that has both of them | |
119 | as its parents. | |
ffb1a4be | 120 | |
ebef7e50 JN |
121 | A merged version reconciling the changes from all branches to be |
122 | merged is committed, and your `HEAD`, index, and working tree are | |
123 | updated to it. It is possible to have modifications in the working | |
124 | tree as long as they do not overlap; the update will preserve them. | |
ffb1a4be | 125 | |
ebef7e50 JN |
126 | When it is not obvious how to reconcile the changes, the following |
127 | happens: | |
ffb1a4be | 128 | |
ebef7e50 JN |
129 | 1. The `HEAD` pointer stays the same. |
130 | 2. The `MERGE_HEAD` ref is set to point to the other branch head. | |
131 | 3. Paths that merged cleanly are updated both in the index file and | |
ffb1a4be | 132 | in your working tree. |
ebef7e50 JN |
133 | 4. For conflicting paths, the index file records up to three |
134 | versions: stage 1 stores the version from the common ancestor, | |
135 | stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you | |
b1889c36 | 136 | can inspect the stages with `git ls-files -u`). The working |
29b802aa | 137 | tree files contain the result of the "merge" program; i.e. 3-way |
ebef7e50 JN |
138 | merge results with familiar conflict markers `<<<` `===` `>>>`. |
139 | 5. No other changes are made. In particular, the local | |
ffb1a4be JH |
140 | modifications you had before you started merge will stay the |
141 | same and the index entries for them stay as they were, | |
142 | i.e. matching `HEAD`. | |
143 | ||
ed4a6baa JN |
144 | If you tried a merge which resulted in complex conflicts and |
145 | want to start over, you can recover with `git reset --merge`. | |
146 | ||
70a3f897 JH |
147 | HOW CONFLICTS ARE PRESENTED |
148 | --------------------------- | |
149 | ||
150 | During a merge, the working tree files are updated to reflect the result | |
151 | of the merge. Among the changes made to the common ancestor's version, | |
152 | non-overlapping ones (that is, you changed an area of the file while the | |
153 | other side left that area intact, or vice versa) are incorporated in the | |
154 | final result verbatim. When both sides made changes to the same area, | |
155 | however, git cannot randomly pick one side over the other, and asks you to | |
156 | resolve it by leaving what both sides did to that area. | |
157 | ||
158 | By default, git uses the same style as that is used by "merge" program | |
159 | from the RCS suite to present such a conflicted hunk, like this: | |
160 | ||
161 | ------------ | |
162 | Here are lines that are either unchanged from the common | |
163 | ancestor, or cleanly resolved because only one side changed. | |
164 | <<<<<<< yours:sample.txt | |
165 | Conflict resolution is hard; | |
166 | let's go shopping. | |
167 | ======= | |
168 | Git makes conflict resolution easy. | |
169 | >>>>>>> theirs:sample.txt | |
170 | And here is another line that is cleanly resolved or unmodified. | |
171 | ------------ | |
172 | ||
29b802aa | 173 | The area where a pair of conflicting changes happened is marked with markers |
dcb11263 | 174 | `<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` |
29b802aa | 175 | is typically your side, and the part afterwards is typically their side. |
70a3f897 | 176 | |
29b802aa RW |
177 | The default format does not show what the original said in the conflicting |
178 | area. You cannot tell how many lines are deleted and replaced with | |
179 | Barbie's remark on your side. The only thing you can tell is that your | |
70a3f897 JH |
180 | side wants to say it is hard and you'd prefer to go shopping, while the |
181 | other side wants to claim it is easy. | |
182 | ||
183 | An alternative style can be used by setting the "merge.conflictstyle" | |
184 | configuration variable to "diff3". In "diff3" style, the above conflict | |
185 | may look like this: | |
186 | ||
187 | ------------ | |
188 | Here are lines that are either unchanged from the common | |
189 | ancestor, or cleanly resolved because only one side changed. | |
190 | <<<<<<< yours:sample.txt | |
191 | Conflict resolution is hard; | |
192 | let's go shopping. | |
193 | ||||||| | |
194 | Conflict resolution is hard. | |
195 | ======= | |
196 | Git makes conflict resolution easy. | |
197 | >>>>>>> theirs:sample.txt | |
198 | And here is another line that is cleanly resolved or unmodified. | |
199 | ------------ | |
200 | ||
dcb11263 CJ |
201 | In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses |
202 | another `|||||||` marker that is followed by the original text. You can | |
70a3f897 JH |
203 | tell that the original just stated a fact, and your side simply gave in to |
204 | that statement and gave up, while the other side tried to have a more | |
205 | positive attitude. You can sometimes come up with a better resolution by | |
206 | viewing the original. | |
207 | ||
208 | ||
209 | HOW TO RESOLVE CONFLICTS | |
210 | ------------------------ | |
211 | ||
ffb1a4be JH |
212 | After seeing a conflict, you can do two things: |
213 | ||
29b802aa | 214 | * Decide not to merge. The only clean-ups you need are to reset |
ffb1a4be | 215 | the index file to the `HEAD` commit to reverse 2. and to clean |
ca768288 | 216 | up working tree changes made by 2. and 3.; `git-reset --hard` can |
ffb1a4be JH |
217 | be used for this. |
218 | ||
34ad1afa DH |
219 | * Resolve the conflicts. Git will mark the conflicts in |
220 | the working tree. Edit the files into shape and | |
0b444cdb | 221 | 'git add' them to the index. Use 'git commit' to seal the deal. |
ffb1a4be | 222 | |
34ad1afa DH |
223 | You can work through the conflict with a number of tools: |
224 | ||
ca768288 | 225 | * Use a mergetool. `git mergetool` to launch a graphical |
34ad1afa DH |
226 | mergetool which will work you through the merge. |
227 | ||
ca768288 | 228 | * Look at the diffs. `git diff` will show a three-way diff, |
3588cf94 JN |
229 | highlighting changes from both the `HEAD` and `MERGE_HEAD` |
230 | versions. | |
34ad1afa | 231 | |
3588cf94 JN |
232 | * Look at the diffs from each branch. `git log --merge -p <path>` |
233 | will show diffs first for the `HEAD` version and then the | |
234 | `MERGE_HEAD` version. | |
34ad1afa | 235 | |
ca768288 | 236 | * Look at the originals. `git show :1:filename` shows the |
3588cf94 JN |
237 | common ancestor, `git show :2:filename` shows the `HEAD` |
238 | version, and `git show :3:filename` shows the `MERGE_HEAD` | |
239 | version. | |
ffb1a4be | 240 | |
d504f697 CB |
241 | |
242 | EXAMPLES | |
243 | -------- | |
244 | ||
245 | * Merge branches `fixes` and `enhancements` on top of | |
246 | the current branch, making an octopus merge: | |
247 | + | |
248 | ------------------------------------------------ | |
249 | $ git merge fixes enhancements | |
250 | ------------------------------------------------ | |
251 | ||
252 | * Merge branch `obsolete` into the current branch, using `ours` | |
253 | merge strategy: | |
254 | + | |
255 | ------------------------------------------------ | |
256 | $ git merge -s ours obsolete | |
257 | ------------------------------------------------ | |
258 | ||
259 | * Merge branch `maint` into the current branch, but do not make | |
260 | a new commit automatically: | |
261 | + | |
262 | ------------------------------------------------ | |
263 | $ git merge --no-commit maint | |
264 | ------------------------------------------------ | |
265 | + | |
266 | This can be used when you want to include further changes to the | |
267 | merge, or want to write your own merge commit message. | |
268 | + | |
269 | You should refrain from abusing this option to sneak substantial | |
270 | changes into a merge commit. Small fixups like bumping | |
271 | release/version name would be acceptable. | |
272 | ||
273 | ||
a4081bac JN |
274 | include::merge-strategies.txt[] |
275 | ||
35e9d630 JN |
276 | CONFIGURATION |
277 | ------------- | |
278 | include::merge-config.txt[] | |
279 | ||
280 | branch.<name>.mergeoptions:: | |
281 | Sets default options for merging into branch <name>. The syntax and | |
282 | supported options are the same as those of 'git merge', but option | |
283 | values containing whitespace characters are currently not supported. | |
284 | ||
3c64314c PB |
285 | SEE ALSO |
286 | -------- | |
5162e697 | 287 | linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], |
483bc4f0 JN |
288 | linkgit:gitattributes[5], |
289 | linkgit:git-reset[1], | |
290 | linkgit:git-diff[1], linkgit:git-ls-files[1], | |
291 | linkgit:git-add[1], linkgit:git-rm[1], | |
292 | linkgit:git-mergetool[1] | |
3c64314c | 293 | |
0f69be53 JH |
294 | Author |
295 | ------ | |
59eb68aa | 296 | Written by Junio C Hamano <gitster@pobox.com> |
0f69be53 JH |
297 | |
298 | ||
299 | Documentation | |
300 | -------------- | |
301 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
302 | ||
303 | GIT | |
304 | --- | |
9e1f0a85 | 305 | Part of the linkgit:git[1] suite |