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