]>
Commit | Line | Data |
---|---|---|
c16e30c0 JH |
1 | git-merge-tree(1) |
2 | ================= | |
3 | ||
4 | NAME | |
5 | ---- | |
1f0c3a29 | 6 | git-merge-tree - Perform merge without touching index or working tree |
c16e30c0 JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
a1a78119 | 12 | 'git merge-tree' [--write-tree] [<options>] <branch1> <branch2> |
1f0c3a29 | 13 | 'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated) |
c16e30c0 | 14 | |
1f0c3a29 | 15 | [[NEWMERGE]] |
c16e30c0 JH |
16 | DESCRIPTION |
17 | ----------- | |
1f0c3a29 EN |
18 | |
19 | This command has a modern `--write-tree` mode and a deprecated | |
20 | `--trivial-merge` mode. With the exception of the | |
21 | <<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of | |
22 | this documentation describes modern `--write-tree` mode. | |
23 | ||
24 | Performs a merge, but does not make any new commits and does not read | |
25 | from or write to either the working tree or index. | |
26 | ||
27 | The performed merge will use the same feature as the "real" | |
28 | linkgit:git-merge[1], including: | |
29 | ||
30 | * three way content merges of individual files | |
31 | * rename detection | |
32 | * proper directory/file conflict handling | |
33 | * recursive ancestor consolidation (i.e. when there is more than one | |
34 | merge base, creating a virtual merge base by merging the merge bases) | |
35 | * etc. | |
36 | ||
37 | After the merge completes, a new toplevel tree object is created. See | |
38 | `OUTPUT` below for details. | |
39 | ||
a1a78119 EN |
40 | OPTIONS |
41 | ------- | |
42 | ||
7c48b278 EN |
43 | -z:: |
44 | Do not quote filenames in the <Conflicted file info> section, | |
45 | and end each filename with a NUL character rather than | |
46 | newline. Also begin the messages section with a NUL character | |
47 | instead of a newline. See <<OUTPUT>> below for more information. | |
48 | ||
b520bc6c EN |
49 | --name-only:: |
50 | In the Conflicted file info section, instead of writing a list | |
51 | of (mode, oid, stage, path) tuples to output for conflicted | |
52 | files, just provide a list of filenames with conflicts (and | |
53 | do not list filenames multiple times if they have multiple | |
54 | conflicting stages). | |
55 | ||
a1a78119 EN |
56 | --[no-]messages:: |
57 | Write any informational messages such as "Auto-merging <path>" | |
58 | or CONFLICT notices to the end of stdout. If unspecified, the | |
59 | default is to include these messages if there are merge | |
60 | conflicts, and to omit them otherwise. | |
61 | ||
7976721d EN |
62 | --allow-unrelated-histories:: |
63 | merge-tree will by default error out if the two branches specified | |
64 | share no common history. This flag can be given to override that | |
65 | check and make the merge proceed anyway. | |
66 | ||
66265a69 KZ |
67 | --merge-base=<commit>:: |
68 | Instead of finding the merge-bases for <branch1> and <branch2>, | |
4cc9eb33 KZ |
69 | specify a merge-base for the merge, and specifying multiple bases is |
70 | currently not supported. This option is incompatible with `--stdin`. | |
66265a69 | 71 | |
1f0c3a29 EN |
72 | [[OUTPUT]] |
73 | OUTPUT | |
74 | ------ | |
75 | ||
a1a78119 EN |
76 | For a successful merge, the output from git-merge-tree is simply one |
77 | line: | |
78 | ||
79 | <OID of toplevel tree> | |
80 | ||
81 | Whereas for a conflicted merge, the output is by default of the form: | |
1f0c3a29 EN |
82 | |
83 | <OID of toplevel tree> | |
b520bc6c | 84 | <Conflicted file info> |
a1a78119 EN |
85 | <Informational messages> |
86 | ||
87 | These are discussed individually below. | |
1f0c3a29 | 88 | |
ec1edbcb EN |
89 | However, there is an exception. If `--stdin` is passed, then there is |
90 | an extra section at the beginning, a NUL character at the end, and then | |
91 | all the sections repeat for each line of input. Thus, if the first merge | |
92 | is conflicted and the second is clean, the output would be of the form: | |
93 | ||
94 | <Merge status> | |
95 | <OID of toplevel tree> | |
96 | <Conflicted file info> | |
97 | <Informational messages> | |
98 | NUL | |
99 | <Merge status> | |
100 | <OID of toplevel tree> | |
101 | NUL | |
102 | ||
103 | [[MS]] | |
104 | Merge status | |
105 | ~~~~~~~~~~~~ | |
106 | ||
107 | This is an integer status followed by a NUL character. The integer status is: | |
108 | ||
109 | 0: merge had conflicts | |
110 | 1: merge was clean | |
f7111175 | 111 | <0: something prevented the merge from running (e.g. access to repository |
ec1edbcb EN |
112 | objects denied by filesystem) |
113 | ||
a1a78119 EN |
114 | [[OIDTLT]] |
115 | OID of toplevel tree | |
116 | ~~~~~~~~~~~~~~~~~~~~ | |
117 | ||
118 | This is a tree object that represents what would be checked out in the | |
119 | working tree at the end of `git merge`. If there were conflicts, then | |
7c48b278 EN |
120 | files within this tree may have embedded conflict markers. This section |
121 | is always followed by a newline (or NUL if `-z` is passed). | |
a1a78119 | 122 | |
7fa33388 | 123 | [[CFI]] |
b520bc6c | 124 | Conflicted file info |
7fa33388 EN |
125 | ~~~~~~~~~~~~~~~~~~~~ |
126 | ||
b520bc6c EN |
127 | This is a sequence of lines with the format |
128 | ||
129 | <mode> <object> <stage> <filename> | |
130 | ||
131 | The filename will be quoted as explained for the configuration | |
132 | variable `core.quotePath` (see linkgit:git-config[1]). However, if | |
133 | the `--name-only` option is passed, the mode, object, and stage will | |
7c48b278 EN |
134 | be omitted. If `-z` is passed, the "lines" are terminated by a NUL |
135 | character instead of a newline character. | |
7fa33388 | 136 | |
a1a78119 EN |
137 | [[IM]] |
138 | Informational messages | |
139 | ~~~~~~~~~~~~~~~~~~~~~~ | |
140 | ||
a9f5bb83 EN |
141 | This section provides informational messages, typically about |
142 | conflicts. The format of the section varies significantly depending | |
143 | on whether `-z` is passed. | |
144 | ||
145 | If `-z` is passed: | |
146 | ||
147 | The output format is zero or more conflict informational records, each | |
148 | of the form: | |
149 | ||
150 | <list-of-paths><conflict-type>NUL<conflict-message>NUL | |
151 | ||
152 | where <list-of-paths> is of the form | |
153 | ||
154 | <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL | |
155 | ||
156 | and includes paths (or branch names) affected by the conflict or | |
157 | informational message in <conflict-message>. Also, <conflict-type> is a | |
158 | stable string explaining the type of conflict, such as | |
159 | ||
160 | * "Auto-merging" | |
161 | * "CONFLICT (rename/delete)" | |
162 | * "CONFLICT (submodule lacks merge base)" | |
163 | * "CONFLICT (binary)" | |
164 | ||
165 | and <conflict-message> is a more detailed message about the conflict which often | |
166 | (but not always) embeds the <stable-short-type-description> within it. These | |
167 | strings may change in future Git versions. Some examples: | |
a1a78119 EN |
168 | |
169 | * "Auto-merging <file>" | |
170 | * "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..." | |
a9f5bb83 | 171 | * "Failed to merge submodule <submodule> (no merge base)" |
a1a78119 | 172 | * "Warning: cannot merge binary files: <filename>" |
1f0c3a29 | 173 | |
a9f5bb83 EN |
174 | If `-z` is NOT passed: |
175 | ||
176 | This section starts with a blank line to separate it from the previous | |
177 | sections, and then only contains the <conflict-message> information | |
178 | from the previous section (separated by newlines). These are | |
179 | non-stable strings that should not be parsed by scripts, and are just | |
180 | meant for human consumption. Also, note that while <conflict-message> | |
181 | strings usually do not contain embedded newlines, they sometimes do. | |
182 | (However, the free-form messages will never have an embedded NUL | |
183 | character). So, the entire block of information is meant for human | |
184 | readers as an agglomeration of all conflict messages. | |
7c48b278 | 185 | |
1f0c3a29 EN |
186 | EXIT STATUS |
187 | ----------- | |
188 | ||
189 | For a successful, non-conflicted merge, the exit status is 0. When the | |
190 | merge has conflicts, the exit status is 1. If the merge is not able to | |
191 | complete (or start) due to some kind of error, the exit status is | |
ec1edbcb EN |
192 | something other than 0 or 1 (and the output is unspecified). When |
193 | --stdin is passed, the return status is 0 for both successful and | |
194 | conflicted merges, and something other than 0 or 1 if it cannot complete | |
195 | all the requested merges. | |
1f0c3a29 EN |
196 | |
197 | USAGE NOTES | |
198 | ----------- | |
199 | ||
200 | This command is intended as low-level plumbing, similar to | |
201 | linkgit:git-hash-object[1], linkgit:git-mktree[1], | |
202 | linkgit:git-commit-tree[1], linkgit:git-write-tree[1], | |
203 | linkgit:git-update-ref[1], and linkgit:git-mktag[1]. Thus, it can be | |
204 | used as a part of a series of steps such as: | |
205 | ||
206 | NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2) | |
207 | test $? -eq 0 || die "There were conflicts..." | |
208 | NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2) | |
209 | git update-ref $BRANCH1 $NEWCOMMIT | |
210 | ||
a1a78119 EN |
211 | Note that when the exit status is non-zero, `NEWTREE` in this sequence |
212 | will contain a lot more output than just a tree. | |
213 | ||
b520bc6c EN |
214 | For conflicts, the output includes the same information that you'd get |
215 | with linkgit:git-merge[1]: | |
216 | ||
217 | * what would be written to the working tree (the | |
218 | <<OIDTLT,OID of toplevel tree>>) | |
219 | * the higher order stages that would be written to the index (the | |
220 | <<CFI,Conflicted file info>>) | |
221 | * any messages that would have been printed to stdout (the | |
222 | <<IM,Informational messages>>) | |
223 | ||
501e3bab KZ |
224 | INPUT FORMAT |
225 | ------------ | |
226 | 'git merge-tree --stdin' input format is fully text based. Each line | |
227 | has this format: | |
228 | ||
229 | [<base-commit> -- ]<branch1> <branch2> | |
230 | ||
231 | If one line is separated by `--`, the string before the separator is | |
232 | used for specifying a merge-base for the merge and the string after | |
233 | the separator describes the branches to be merged. | |
234 | ||
7260e872 EN |
235 | MISTAKES TO AVOID |
236 | ----------------- | |
237 | ||
238 | Do NOT look through the resulting toplevel tree to try to find which | |
239 | files conflict; parse the <<CFI,Conflicted file info>> section instead. | |
240 | Not only would parsing an entire tree be horrendously slow in large | |
241 | repositories, there are numerous types of conflicts not representable by | |
242 | conflict markers (modify/delete, mode conflict, binary file changed on | |
243 | both sides, file/directory conflicts, various rename conflict | |
244 | permutations, etc.) | |
245 | ||
246 | Do NOT interpret an empty <<CFI,Conflicted file info>> list as a clean | |
247 | merge; check the exit status. A merge can have conflicts without having | |
248 | individual files conflict (there are a few types of directory rename | |
249 | conflicts that fall into this category, and others might also be added | |
250 | in the future). | |
251 | ||
252 | Do NOT attempt to guess or make the user guess the conflict types from | |
253 | the <<CFI,Conflicted file info>> list. The information there is | |
254 | insufficient to do so. For example: Rename/rename(1to2) conflicts (both | |
255 | sides renamed the same file differently) will result in three different | |
256 | file having higher order stages (but each only has one higher order | |
257 | stage), with no way (short of the <<IM,Informational messages>> section) | |
258 | to determine which three files are related. File/directory conflicts | |
259 | also result in a file with exactly one higher order stage. | |
260 | Possibly-involved-in-directory-rename conflicts (when | |
261 | "merge.directoryRenames" is unset or set to "conflicts") also result in | |
262 | a file with exactly one higher order stage. In all cases, the | |
263 | <<IM,Informational messages>> section has the necessary info, though it | |
264 | is not designed to be machine parseable. | |
265 | ||
266 | Do NOT assume that each paths from <<CFI,Conflicted file info>>, and | |
267 | the logical conflicts in the <<IM,Informational messages>> have a | |
268 | one-to-one mapping, nor that there is a one-to-many mapping, nor a | |
269 | many-to-one mapping. Many-to-many mappings exist, meaning that each | |
270 | path can have many logical conflict types in a single merge, and each | |
271 | logical conflict type can affect many paths. | |
272 | ||
273 | Do NOT assume all filenames listed in the <<IM,Informational messages>> | |
274 | section had conflicts. Messages can be included for files that have no | |
275 | conflicts, such as "Auto-merging <file>". | |
276 | ||
277 | AVOID taking the OIDS from the <<CFI,Conflicted file info>> and | |
278 | re-merging them to present the conflicts to the user. This will lose | |
279 | information. Instead, look up the version of the file found within the | |
280 | <<OIDTLT,OID of toplevel tree>> and show that instead. In particular, | |
281 | the latter will have conflict markers annotated with the original | |
282 | branch/commit being merged and, if renames were involved, the original | |
283 | filename. While you could include the original branch/commit in the | |
284 | conflict marker annotations when re-merging, the original filename is | |
285 | not available from the <<CFI,Conflicted file info>> and thus you would | |
286 | be losing information that might help the user resolve the conflict. | |
287 | ||
1f0c3a29 EN |
288 | [[DEPMERGE]] |
289 | DEPRECATED DESCRIPTION | |
290 | ---------------------- | |
291 | ||
292 | Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this | |
293 | documentation, this section describes the deprecated `--trivial-merge` | |
294 | mode. | |
295 | ||
296 | Other than the optional `--trivial-merge`, this mode accepts no | |
297 | options. | |
298 | ||
299 | This mode reads three tree-ish, and outputs trivial merge results and | |
300 | conflicting stages to the standard output in a semi-diff format. | |
301 | Since this was designed for higher level scripts to consume and merge | |
302 | the results back into the index, it omits entries that match | |
303 | <branch1>. The result of this second form is similar to what | |
304 | three-way 'git read-tree -m' does, but instead of storing the results | |
305 | in the index, the command outputs the entries to the standard output. | |
306 | ||
307 | This form not only has limited applicability (a trivial merge cannot | |
308 | handle content merges of individual files, rename detection, proper | |
309 | directory/file conflict handling, etc.), the output format is also | |
310 | difficult to work with, and it will generally be less performant than | |
311 | the first form even on successful merges (especially if working in | |
312 | large repositories). | |
c16e30c0 | 313 | |
c16e30c0 JH |
314 | GIT |
315 | --- | |
9e1f0a85 | 316 | Part of the linkgit:git[1] suite |