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