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