6 git-merge-tree - Perform merge without touching index or working tree
12 'git merge-tree' [--write-tree] [<options>] <branch1> <branch2>
13 'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
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.
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.
27 The performed merge will use the same feature as the "real"
28 linkgit:git-merge[1], including:
30 * three way content merges of individual files
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)
37 After the merge completes, a new toplevel tree object is created. See
38 `OUTPUT` below for details.
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.
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
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.
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.
71 For a successful merge, the output from git-merge-tree is simply one
74 <OID of toplevel tree>
76 Whereas for a conflicted merge, the output is by default of the form:
78 <OID of toplevel tree>
79 <Conflicted file info>
80 <Informational messages>
82 These are discussed individually below.
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:
90 <OID of toplevel tree>
91 <Conflicted file info>
92 <Informational messages>
95 <OID of toplevel tree>
102 This is an integer status followed by a NUL character. The integer status is:
104 0: merge had conflicts
106 <0: something prevented the merge from running (e.g. access to repository
107 objects denied by filesystem)
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
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).
122 This is a sequence of lines with the format
124 <mode> <object> <stage> <filename>
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
129 be omitted. If `-z` is passed, the "lines" are terminated by a NUL
130 character instead of a newline character.
133 Informational messages
134 ~~~~~~~~~~~~~~~~~~~~~~
136 This section provides informational messages, typically about
137 conflicts. The format of the section varies significantly depending
138 on whether `-z` is passed.
142 The output format is zero or more conflict informational records, each
145 <list-of-paths><conflict-type>NUL<conflict-message>NUL
147 where <list-of-paths> is of the form
149 <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL
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
156 * "CONFLICT (rename/delete)"
157 * "CONFLICT (submodule lacks merge base)"
158 * "CONFLICT (binary)"
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:
164 * "Auto-merging <file>"
165 * "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..."
166 * "Failed to merge submodule <submodule> (no merge base)"
167 * "Warning: cannot merge binary files: <filename>"
169 If `-z` is NOT passed:
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.
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
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.
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:
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
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.
209 For conflicts, the output includes the same information that you'd get
210 with linkgit:git-merge[1]:
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>>)
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
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
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.
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.
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>".
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.
273 DEPRECATED DESCRIPTION
274 ----------------------
276 Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this
277 documentation, this section describes the deprecated `--trivial-merge`
280 Other than the optional `--trivial-merge`, this mode accepts no
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.
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
300 Part of the linkgit:git[1] suite