]>
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] |
b1889c36 | 12 | 'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]... |
22f1fb66 | 13 | [-m <msg>] <remote>... |
b1889c36 | 14 | 'git merge' <msg> HEAD <remote>... |
0f69be53 JH |
15 | |
16 | DESCRIPTION | |
17 | ----------- | |
17bcdad3 | 18 | This is the top-level interface to the merge machinery |
0f69be53 JH |
19 | which drives multiple merge strategy scripts. |
20 | ||
dee48c3c JH |
21 | The second syntax (<msg> `HEAD` <remote>) is supported for |
22 | historical reasons. Do not use it from the command line or in | |
23 | new scripts. It is the same as `git merge -m <msg> <remote>`. | |
24 | ||
0f69be53 JH |
25 | |
26 | OPTIONS | |
27 | ------- | |
93d69d86 | 28 | include::merge-options.txt[] |
0f69be53 | 29 | |
dee48c3c | 30 | -m <msg>:: |
0f8a02c6 JN |
31 | Set the commit message to be used for the merge commit (in |
32 | case one is created). The 'git fmt-merge-msg' command can be | |
33 | used to give a good default for automated 'git merge' | |
34 | invocations. | |
3c64314c | 35 | |
f448e24e AMS |
36 | <remote>...:: |
37 | Other branch heads to merge into our branch. You need at | |
0f69be53 JH |
38 | least one <remote>. Specifying more than one <remote> |
39 | obviously means you are trying an Octopus. | |
40 | ||
bb73d73c JL |
41 | include::merge-strategies.txt[] |
42 | ||
0f69be53 | 43 | |
9fe00538 | 44 | If you tried a merge which resulted in complex conflicts and |
4fa535a1 | 45 | want to start over, you can recover with 'git-reset'. |
3ae854c3 | 46 | |
dbddb714 JN |
47 | CONFIGURATION |
48 | ------------- | |
f5a84c37 | 49 | include::merge-config.txt[] |
dbddb714 | 50 | |
aec7b362 LH |
51 | branch.<name>.mergeoptions:: |
52 | Sets default options for merging into branch <name>. The syntax and | |
25dcc0d6 JN |
53 | supported options are the same as those of 'git merge', but option |
54 | values containing whitespace characters are currently not supported. | |
3ae854c3 | 55 | |
ffb1a4be JH |
56 | HOW MERGE WORKS |
57 | --------------- | |
58 | ||
59 | A merge is always between the current `HEAD` and one or more | |
81646ad2 | 60 | commits (usually, branch head or tag), and the index file must |
c0be8aa0 PB |
61 | match the tree of `HEAD` commit (i.e. the contents of the last commit) |
62 | when it starts out. In other words, `git diff --cached HEAD` must | |
63 | report no changes. (One exception is when the changed index | |
64 | entries are already in the same state that would result from | |
65 | the merge anyway.) | |
66 | ||
67 | Three kinds of merge can happen: | |
68 | ||
69 | * The merged commit is already contained in `HEAD`. This is the | |
70 | simplest case, called "Already up-to-date." | |
71 | ||
72 | * `HEAD` is already contained in the merged commit. This is the | |
29b802aa RW |
73 | most common case especially when invoked from 'git pull': |
74 | you are tracking an upstream repository, have committed no local | |
c0be8aa0 | 75 | changes and now you want to update to a newer upstream revision. |
29b802aa | 76 | Your `HEAD` (and the index) is updated to point at the merged |
c0be8aa0 PB |
77 | commit, without creating an extra merge commit. This is |
78 | called "Fast-forward". | |
79 | ||
80 | * Both the merged commit and `HEAD` are independent and must be | |
29b802aa | 81 | tied together by a merge commit that has both of them as its parents. |
c0be8aa0 PB |
82 | The rest of this section describes this "True merge" case. |
83 | ||
84 | The chosen merge strategy merges the two commits into a single | |
85 | new source tree. | |
29b802aa | 86 | When things merge cleanly, this is what happens: |
ffb1a4be | 87 | |
434e6ef8 SH |
88 | 1. The results are updated both in the index file and in your |
89 | working tree; | |
90 | 2. Index file is written out as a tree; | |
91 | 3. The tree gets committed; and | |
92 | 4. The `HEAD` pointer gets advanced. | |
ffb1a4be JH |
93 | |
94 | Because of 2., we require that the original state of the index | |
29b802aa | 95 | file matches exactly the current `HEAD` commit; otherwise we |
ffb1a4be JH |
96 | will write out your local changes already registered in your |
97 | index file along with the merge result, which is not good. | |
29b802aa | 98 | Because 1. involves only those paths differing between your |
ffb1a4be JH |
99 | branch and the remote branch you are pulling from during the |
100 | merge (which is typically a fraction of the whole tree), you can | |
101 | have local modifications in your working tree as long as they do | |
102 | not overlap with what the merge updates. | |
103 | ||
29b802aa | 104 | When there are conflicts, the following happens: |
ffb1a4be JH |
105 | |
106 | 1. `HEAD` stays the same. | |
107 | ||
108 | 2. Cleanly merged paths are updated both in the index file and | |
109 | in your working tree. | |
110 | ||
3ace1fe3 JH |
111 | 3. For conflicting paths, the index file records up to three |
112 | versions; stage1 stores the version from the common ancestor, | |
113 | stage2 from `HEAD`, and stage3 from the remote branch (you | |
b1889c36 | 114 | can inspect the stages with `git ls-files -u`). The working |
29b802aa RW |
115 | tree files contain the result of the "merge" program; i.e. 3-way |
116 | merge results with familiar conflict markers `<<< === >>>`. | |
ffb1a4be JH |
117 | |
118 | 4. No other changes are done. In particular, the local | |
119 | modifications you had before you started merge will stay the | |
120 | same and the index entries for them stay as they were, | |
121 | i.e. matching `HEAD`. | |
122 | ||
70a3f897 JH |
123 | HOW CONFLICTS ARE PRESENTED |
124 | --------------------------- | |
125 | ||
126 | During a merge, the working tree files are updated to reflect the result | |
127 | of the merge. Among the changes made to the common ancestor's version, | |
128 | non-overlapping ones (that is, you changed an area of the file while the | |
129 | other side left that area intact, or vice versa) are incorporated in the | |
130 | final result verbatim. When both sides made changes to the same area, | |
131 | however, git cannot randomly pick one side over the other, and asks you to | |
132 | resolve it by leaving what both sides did to that area. | |
133 | ||
134 | By default, git uses the same style as that is used by "merge" program | |
135 | from the RCS suite to present such a conflicted hunk, like this: | |
136 | ||
137 | ------------ | |
138 | Here are lines that are either unchanged from the common | |
139 | ancestor, or cleanly resolved because only one side changed. | |
140 | <<<<<<< yours:sample.txt | |
141 | Conflict resolution is hard; | |
142 | let's go shopping. | |
143 | ======= | |
144 | Git makes conflict resolution easy. | |
145 | >>>>>>> theirs:sample.txt | |
146 | And here is another line that is cleanly resolved or unmodified. | |
147 | ------------ | |
148 | ||
29b802aa | 149 | The area where a pair of conflicting changes happened is marked with markers |
dcb11263 | 150 | `<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======` |
29b802aa | 151 | is typically your side, and the part afterwards is typically their side. |
70a3f897 | 152 | |
29b802aa RW |
153 | The default format does not show what the original said in the conflicting |
154 | area. You cannot tell how many lines are deleted and replaced with | |
155 | Barbie's remark on your side. The only thing you can tell is that your | |
70a3f897 JH |
156 | side wants to say it is hard and you'd prefer to go shopping, while the |
157 | other side wants to claim it is easy. | |
158 | ||
159 | An alternative style can be used by setting the "merge.conflictstyle" | |
160 | configuration variable to "diff3". In "diff3" style, the above conflict | |
161 | may look like this: | |
162 | ||
163 | ------------ | |
164 | Here are lines that are either unchanged from the common | |
165 | ancestor, or cleanly resolved because only one side changed. | |
166 | <<<<<<< yours:sample.txt | |
167 | Conflict resolution is hard; | |
168 | let's go shopping. | |
169 | ||||||| | |
170 | Conflict resolution is hard. | |
171 | ======= | |
172 | Git makes conflict resolution easy. | |
173 | >>>>>>> theirs:sample.txt | |
174 | And here is another line that is cleanly resolved or unmodified. | |
175 | ------------ | |
176 | ||
dcb11263 CJ |
177 | In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses |
178 | another `|||||||` marker that is followed by the original text. You can | |
70a3f897 JH |
179 | tell that the original just stated a fact, and your side simply gave in to |
180 | that statement and gave up, while the other side tried to have a more | |
181 | positive attitude. You can sometimes come up with a better resolution by | |
182 | viewing the original. | |
183 | ||
184 | ||
185 | HOW TO RESOLVE CONFLICTS | |
186 | ------------------------ | |
187 | ||
ffb1a4be JH |
188 | After seeing a conflict, you can do two things: |
189 | ||
29b802aa | 190 | * Decide not to merge. The only clean-ups you need are to reset |
ffb1a4be | 191 | the index file to the `HEAD` commit to reverse 2. and to clean |
c0be8aa0 | 192 | up working tree changes made by 2. and 3.; 'git-reset --hard' can |
ffb1a4be JH |
193 | be used for this. |
194 | ||
34ad1afa DH |
195 | * Resolve the conflicts. Git will mark the conflicts in |
196 | the working tree. Edit the files into shape and | |
29b802aa | 197 | 'git-add' them to the index. Use 'git-commit' to seal the deal. |
ffb1a4be | 198 | |
34ad1afa DH |
199 | You can work through the conflict with a number of tools: |
200 | ||
201 | * Use a mergetool. 'git mergetool' to launch a graphical | |
202 | mergetool which will work you through the merge. | |
203 | ||
204 | * Look at the diffs. 'git diff' will show a three-way diff, | |
205 | highlighting changes from both the HEAD and remote versions. | |
206 | ||
207 | * Look at the diffs on their own. 'git log --merge -p <path>' | |
208 | will show diffs first for the HEAD version and then the | |
209 | remote version. | |
210 | ||
211 | * Look at the originals. 'git show :1:filename' shows the | |
212 | common ancestor, 'git show :2:filename' shows the HEAD | |
213 | version and 'git show :3:filename' shows the remote version. | |
ffb1a4be | 214 | |
3c64314c PB |
215 | SEE ALSO |
216 | -------- | |
5162e697 | 217 | linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], |
483bc4f0 JN |
218 | linkgit:gitattributes[5], |
219 | linkgit:git-reset[1], | |
220 | linkgit:git-diff[1], linkgit:git-ls-files[1], | |
221 | linkgit:git-add[1], linkgit:git-rm[1], | |
222 | linkgit:git-mergetool[1] | |
3c64314c | 223 | |
0f69be53 JH |
224 | Author |
225 | ------ | |
59eb68aa | 226 | Written by Junio C Hamano <gitster@pobox.com> |
0f69be53 JH |
227 | |
228 | ||
229 | Documentation | |
230 | -------------- | |
231 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
232 | ||
233 | GIT | |
234 | --- | |
9e1f0a85 | 235 | Part of the linkgit:git[1] suite |