<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="git-merge-tree(1)">
    <title>git-merge-tree(1)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>git-merge-tree(1)</primary>
</indexterm>
<simplesect id="git-merge-tree(1)__name">
<title>NAME</title>
<simpara>git-merge-tree - Perform merge without touching index or working tree</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)__synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git merge-tree</emphasis> [--write-tree] [&lt;options&gt;] &lt;branch1&gt; &lt;branch2&gt;
<emphasis>git merge-tree</emphasis> [--trivial-merge] &lt;base-tree&gt; &lt;branch1&gt; &lt;branch2&gt; (deprecated)</literallayout>
</blockquote>
</simplesect>
<simplesect id="git-merge-tree(1)_NEWMERGE">
<title>DESCRIPTION</title>
<simpara>This command has a modern <emphasis>--write-tree</emphasis> mode and a deprecated
<emphasis>--trivial-merge</emphasis> mode.  With the exception of the
<link linkend="git-merge-tree(1)_DEPMERGE">DEPRECATED DESCRIPTION</link> section at the end, the rest of
this documentation describes the modern <emphasis>--write-tree</emphasis> mode.</simpara>
<simpara>Performs a merge, but does not make any new commits and does not read
from or write to either the working tree or index.</simpara>
<simpara>The performed merge will use the same features as the "real"
<xref linkend="git-merge(1)" />, including:</simpara>
<itemizedlist>
<listitem>
<simpara>
three way content merges of individual files
</simpara>
</listitem>
<listitem>
<simpara>
rename detection
</simpara>
</listitem>
<listitem>
<simpara>
proper directory/file conflict handling
</simpara>
</listitem>
<listitem>
<simpara>
recursive ancestor consolidation (i.e. when there is more than one
    merge base, creating a virtual merge base by merging the merge bases)
</simpara>
</listitem>
<listitem>
<simpara>
etc.
</simpara>
</listitem>
</itemizedlist>
<simpara>After the merge completes, a new toplevel tree object is created.  See
<emphasis>OUTPUT</emphasis> below for details.</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)__options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-z
</term>
<listitem>
<simpara>
        Do not quote filenames in the &lt;Conflicted file info&gt; section,
        and end each filename with a NUL character rather than
        newline.  Also begin the messages section with a NUL character
        instead of a newline.  See <xref linkend="git-merge-tree(1)_OUTPUT"/> below for more information.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--name-only
</term>
<listitem>
<simpara>
        In the Conflicted file info section, instead of writing a list
        of (mode, oid, stage, path) tuples to output for conflicted
        files, just provide a list of filenames with conflicts (and
        do not list filenames multiple times if they have multiple
        conflicting stages).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--[no-]messages
</term>
<listitem>
<simpara>
        Write any informational messages such as "Auto-merging &lt;path&gt;"
        or CONFLICT notices to the end of stdout.  If unspecified, the
        default is to include these messages if there are merge
        conflicts, and to omit them otherwise.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--allow-unrelated-histories
</term>
<listitem>
<simpara>
        merge-tree will by default error out if the two branches specified
        share no common history.  This flag can be given to override that
        check and make the merge proceed anyway.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--merge-base=&lt;tree-ish&gt;
</term>
<listitem>
<simpara>
        Instead of finding the merge-bases for &lt;branch1&gt; and &lt;branch2&gt;,
        specify a merge-base for the merge, and specifying multiple bases is
        currently not supported. This option is incompatible with <emphasis>--stdin</emphasis>.
</simpara>
<simpara>As the merge-base is provided directly, &lt;branch1&gt; and &lt;branch2&gt; do not need
to specify commits; trees are enough.</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-X&lt;option&gt;
</term>
<term>
--strategy-option=&lt;option&gt;
</term>
<listitem>
<simpara>
        Pass the merge strategy-specific option through to the merge strategy.
        See <xref linkend="git-merge(1)" /> for details.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-merge-tree(1)_OUTPUT">
<title>OUTPUT</title>
<simpara>For a successful merge, the output from git-merge-tree is simply one
line:</simpara>
<literallayout class="monospaced">&lt;OID of toplevel tree&gt;</literallayout>
<simpara>Whereas for a conflicted merge, the output is by default of the form:</simpara>
<literallayout class="monospaced">&lt;OID of toplevel tree&gt;
&lt;Conflicted file info&gt;
&lt;Informational messages&gt;</literallayout>
<simpara>These are discussed individually below.</simpara>
<simpara>However, there is an exception.  If <emphasis>--stdin</emphasis> is passed, then there is
an extra section at the beginning, a NUL character at the end, and then
all the sections repeat for each line of input.  Thus, if the first merge
is conflicted and the second is clean, the output would be of the form:</simpara>
<literallayout class="monospaced">&lt;Merge status&gt;
&lt;OID of toplevel tree&gt;
&lt;Conflicted file info&gt;
&lt;Informational messages&gt;
NUL
&lt;Merge status&gt;
&lt;OID of toplevel tree&gt;
NUL</literallayout>
<section id="git-merge-tree(1)_MS">
<title>Merge status</title>
<simpara>This is an integer status followed by a NUL character.  The integer status is:</simpara>
<literallayout class="monospaced">0: merge had conflicts
1: merge was clean
&lt;0: something prevented the merge from running (e.g. access to repository
    objects denied by filesystem)</literallayout>
</section>
<section id="git-merge-tree(1)_OIDTLT">
<title>OID of toplevel tree</title>
<simpara>This is a tree object that represents what would be checked out in the
working tree at the end of <emphasis>git merge</emphasis>.  If there were conflicts, then
files within this tree may have embedded conflict markers.  This section
is always followed by a newline (or NUL if <emphasis>-z</emphasis> is passed).</simpara>
</section>
<section id="git-merge-tree(1)_CFI">
<title>Conflicted file info</title>
<simpara>This is a sequence of lines with the format</simpara>
<literallayout class="monospaced">&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;filename&gt;</literallayout>
<simpara>The filename will be quoted as explained for the configuration
variable <emphasis>core.quotePath</emphasis> (see <xref linkend="git-config(1)" />).  However, if
the <emphasis>--name-only</emphasis> option is passed, the mode, object, and stage will
be omitted.  If <emphasis>-z</emphasis> is passed, the "lines" are terminated by a NUL
character instead of a newline character.</simpara>
</section>
<section id="git-merge-tree(1)_IM">
<title>Informational messages</title>
<simpara>This section provides informational messages, typically about
conflicts.  The format of the section varies significantly depending
on whether <emphasis>-z</emphasis> is passed.</simpara>
<simpara>If <emphasis>-z</emphasis> is passed:</simpara>
<simpara>The output format is zero or more conflict informational records, each
of the form:</simpara>
<literallayout class="monospaced">&lt;list-of-paths&gt;&lt;conflict-type&gt;NUL&lt;conflict-message&gt;NUL</literallayout>
<simpara>where &lt;list-of-paths&gt; is of the form</simpara>
<literallayout class="monospaced">&lt;number-of-paths&gt;NUL&lt;path1&gt;NUL&lt;path2&gt;NUL...&lt;pathN&gt;NUL</literallayout>
<simpara>and includes paths (or branch names) affected by the conflict or
informational message in &lt;conflict-message&gt;.  Also, &lt;conflict-type&gt; is a
stable string explaining the type of conflict, such as</simpara>
<itemizedlist>
<listitem>
<simpara>
"Auto-merging"
</simpara>
</listitem>
<listitem>
<simpara>
"CONFLICT (rename/delete)"
</simpara>
</listitem>
<listitem>
<simpara>
"CONFLICT (submodule lacks merge base)"
</simpara>
</listitem>
<listitem>
<simpara>
"CONFLICT (binary)"
</simpara>
</listitem>
</itemizedlist>
<simpara>and &lt;conflict-message&gt; is a more detailed message about the conflict which often
(but not always) embeds the &lt;stable-short-type-description&gt; within it.  These
strings may change in future Git versions.  Some examples:</simpara>
<itemizedlist>
<listitem>
<simpara>
"Auto-merging &lt;file&gt;"
</simpara>
</listitem>
<listitem>
<simpara>
"CONFLICT (rename/delete): &lt;oldfile&gt; renamed&#8230;but deleted in&#8230;"
</simpara>
</listitem>
<listitem>
<simpara>
"Failed to merge submodule &lt;submodule&gt; (no merge base)"
</simpara>
</listitem>
<listitem>
<simpara>
"Warning: cannot merge binary files: &lt;filename&gt;"
</simpara>
</listitem>
</itemizedlist>
<simpara>If <emphasis>-z</emphasis> is NOT passed:</simpara>
<simpara>This section starts with a blank line to separate it from the previous
sections, and then only contains the &lt;conflict-message&gt; information
from the previous section (separated by newlines).  These are
non-stable strings that should not be parsed by scripts, and are just
meant for human consumption.  Also, note that while &lt;conflict-message&gt;
strings usually do not contain embedded newlines, they sometimes do.
(However, the free-form messages will never have an embedded NUL
character).  So, the entire block of information is meant for human
readers as an agglomeration of all conflict messages.</simpara>
</section>
</simplesect>
<simplesect id="git-merge-tree(1)__exit_status">
<title>EXIT STATUS</title>
<simpara>For a successful, non-conflicted merge, the exit status is 0.  When the
merge has conflicts, the exit status is 1.  If the merge is not able to
complete (or start) due to some kind of error, the exit status is
something other than 0 or 1 (and the output is unspecified).  When
--stdin is passed, the return status is 0 for both successful and
conflicted merges, and something other than 0 or 1 if it cannot complete
all the requested merges.</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)__usage_notes">
<title>USAGE NOTES</title>
<simpara>This command is intended as low-level plumbing, similar to
<xref linkend="git-hash-object(1)" />, <xref linkend="git-mktree(1)" />,
<xref linkend="git-commit-tree(1)" />, <xref linkend="git-write-tree(1)" />,
<xref linkend="git-update-ref(1)" />, and <xref linkend="git-mktag(1)" />.  Thus, it can be
used as a part of a series of steps such as:</simpara>
<literallayout class="monospaced">NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2)
test $? -eq 0 || die "There were conflicts..."
NEWCOMMIT=$(git commit-tree $NEWTREE -p $BRANCH1 -p $BRANCH2)
git update-ref $BRANCH1 $NEWCOMMIT</literallayout>
<simpara>Note that when the exit status is non-zero, <emphasis>NEWTREE</emphasis> in this sequence
will contain a lot more output than just a tree.</simpara>
<simpara>For conflicts, the output includes the same information that you'd get
with <xref linkend="git-merge(1)" />:</simpara>
<itemizedlist>
<listitem>
<simpara>
what would be written to the working tree (the
    <link linkend="git-merge-tree(1)_OIDTLT">OID of toplevel tree</link>)
</simpara>
</listitem>
<listitem>
<simpara>
the higher order stages that would be written to the index (the
    <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link>)
</simpara>
</listitem>
<listitem>
<simpara>
any messages that would have been printed to stdout (the
    <link linkend="git-merge-tree(1)_IM">Informational messages</link>)
</simpara>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="git-merge-tree(1)__input_format">
<title>INPUT FORMAT</title>
<simpara><emphasis>git merge-tree --stdin</emphasis> input format is fully text based. Each line
has this format:</simpara>
<literallayout class="monospaced">[&lt;base-commit&gt; -- ]&lt;branch1&gt; &lt;branch2&gt;</literallayout>
<simpara>If one line is separated by <emphasis>--</emphasis>, the string before the separator is
used for specifying a merge-base for the merge and the string after
the separator describes the branches to be merged.</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)__mistakes_to_avoid">
<title>MISTAKES TO AVOID</title>
<simpara>Do NOT look through the resulting toplevel tree to try to find which
files conflict; parse the <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link> section instead.
Not only would parsing an entire tree be horrendously slow in large
repositories, there are numerous types of conflicts not representable by
conflict markers (modify/delete, mode conflict, binary file changed on
both sides, file/directory conflicts, various rename conflict
permutations, etc.)</simpara>
<simpara>Do NOT interpret an empty <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link> list as a clean
merge; check the exit status.  A merge can have conflicts without having
individual files conflict (there are a few types of directory rename
conflicts that fall into this category, and others might also be added
in the future).</simpara>
<simpara>Do NOT attempt to guess or make the user guess the conflict types from
the <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link> list.  The information there is
insufficient to do so.  For example: Rename/rename(1to2) conflicts (both
sides renamed the same file differently) will result in three different
files having higher order stages (but each only has one higher order
stage), with no way (short of the <link linkend="git-merge-tree(1)_IM">Informational messages</link> section)
to determine which three files are related.  File/directory conflicts
also result in a file with exactly one higher order stage.
Possibly-involved-in-directory-rename conflicts (when
"merge.directoryRenames" is unset or set to "conflicts") also result in
a file with exactly one higher order stage.  In all cases, the
<link linkend="git-merge-tree(1)_IM">Informational messages</link> section has the necessary info, though it
is not designed to be machine parseable.</simpara>
<simpara>Do NOT assume that each path from <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link>, and
the logical conflicts in the <link linkend="git-merge-tree(1)_IM">Informational messages</link> have a
one-to-one mapping, nor that there is a one-to-many mapping, nor a
many-to-one mapping.  Many-to-many mappings exist, meaning that each
path can have many logical conflict types in a single merge, and each
logical conflict type can affect many paths.</simpara>
<simpara>Do NOT assume all filenames listed in the <link linkend="git-merge-tree(1)_IM">Informational messages</link>
section had conflicts.  Messages can be included for files that have no
conflicts, such as "Auto-merging &lt;file&gt;".</simpara>
<simpara>AVOID taking the OIDS from the <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link> and
re-merging them to present the conflicts to the user.  This will lose
information.  Instead, look up the version of the file found within the
<link linkend="git-merge-tree(1)_OIDTLT">OID of toplevel tree</link> and show that instead.  In particular,
the latter will have conflict markers annotated with the original
branch/commit being merged and, if renames were involved, the original
filename.  While you could include the original branch/commit in the
conflict marker annotations when re-merging, the original filename is
not available from the <link linkend="git-merge-tree(1)_CFI">Conflicted file info</link> and thus you would
be losing information that might help the user resolve the conflict.</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)_DEPMERGE">
<title>DEPRECATED DESCRIPTION</title>
<simpara>Per the <link linkend="git-merge-tree(1)_NEWMERGE">DESCRIPTION</link> and unlike the rest of this
documentation, this section describes the deprecated <emphasis>--trivial-merge</emphasis>
mode.</simpara>
<simpara>Other than the optional <emphasis>--trivial-merge</emphasis>, this mode accepts no
options.</simpara>
<simpara>This mode reads three tree-ish, and outputs trivial merge results and
conflicting stages to the standard output in a semi-diff format.
Since this was designed for higher level scripts to consume and merge
the results back into the index, it omits entries that match
&lt;branch1&gt;.  The result of this second form is similar to what
three-way <emphasis>git read-tree -m</emphasis> does, but instead of storing the results
in the index, the command outputs the entries to the standard output.</simpara>
<simpara>This form not only has limited applicability (a trivial merge cannot
handle content merges of individual files, rename detection, proper
directory/file conflict handling, etc.), the output format is also
difficult to work with, and it will generally be less performant than
the first form even on successful merges (especially if working in
large repositories).</simpara>
</simplesect>
<simplesect id="git-merge-tree(1)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
