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