GIT-MERGE-TREE(1)		  Git Manual		     GIT-MERGE-TREE(1)



NAME
       git-merge-tree - Perform merge without touching index or working tree

SYNOPSIS
       git merge-tree [--write-tree] [<options>] <branch1> <branch2>
       git merge-tree [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)


DESCRIPTION
       This command has a modern --write-tree mode and a deprecated
       --trivial-merge mode. With the exception of the DEPRECATED DESCRIPTION
       section at the end, the rest of this documentation describes modern
       --write-tree mode.

       Performs a merge, but does not make any new commits and does not read
       from or write to either the working tree or index.

       The performed merge will use the same feature as the "real" git-
       merge(1), including:

       o   three way content merges of individual files

       o   rename detection

       o   proper directory/file conflict handling

       o   recursive ancestor consolidation (i.e. when there is more than one
	   merge base, creating a virtual merge base by merging the merge
	   bases)

       o   etc.

       After the merge completes, a new toplevel tree object is created. See
       OUTPUT below for details.

OPTIONS
       -z
	   Do not quote filenames in the <Conflicted file info> 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 the section called "OUTPUT" below for more
	   information.

       --name-only
	   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).

       --[no-]messages
	   Write any informational messages such as "Auto-merging <path>" 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.

       --allow-unrelated-histories
	   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.

OUTPUT
       For a successful merge, the output from git-merge-tree is simply one
       line:

	   <OID of toplevel tree>

       Whereas for a conflicted merge, the output is by default of the form:

	   <OID of toplevel tree>
	   <Conflicted file info>
	   <Informational messages>

       These are discussed individually below.

   OID of toplevel tree
       This is a tree object that represents what would be checked out in the
       working tree at the end of git merge. 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 -z is passed).

   Conflicted file info
       This is a sequence of lines with the format

	   <mode> <object> <stage> <filename>

       The filename will be quoted as explained for the configuration variable
       core.quotePath (see git-config(1)). However, if the --name-only option
       is passed, the mode, object, and stage will be omitted. If -z is
       passed, the "lines" are terminated by a NUL character instead of a
       newline character.

   Informational messages
       This always starts with a blank line (or NUL if -z is passed) to
       separate it from the previous sections, and then has free-form messages
       about the merge, such as:

       o   "Auto-merging <file>"

       o   "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..."

       o   "Failed to merge submodule <submodule> (<reason>)"

       o   "Warning: cannot merge binary files: <filename>"

       Note that these free-form messages will never have a NUL character in
       or between them, even if -z is passed. It is simply a large block of
       text taking up the remainder of the output.

EXIT STATUS
       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).

USAGE NOTES
       This command is intended as low-level plumbing, similar to git-hash-
       object(1), git-mktree(1), git-commit-tree(1), git-write-tree(1), git-
       update-ref(1), and git-mktag(1). Thus, it can be used as a part of a
       series of steps such as:

	   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

       Note that when the exit status is non-zero, NEWTREE in this sequence
       will contain a lot more output than just a tree.

       For conflicts, the output includes the same information that you'd get
       with git-merge(1):

       o   what would be written to the working tree (the OID of toplevel
	   tree)

       o   the higher order stages that would be written to the index (the
	   Conflicted file info)

       o   any messages that would have been printed to stdout (the
	   Informational messages)

MISTAKES TO AVOID
       Do NOT look through the resulting toplevel tree to try to find which
       files conflict; parse the Conflicted file info 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.)

       Do NOT interpret an empty Conflicted file info 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).

       Do NOT attempt to guess or make the user guess the conflict types from
       the Conflicted file info 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 file having
       higher order stages (but each only has one higher order stage), with no
       way (short of the Informational messages 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
       Informational messages section has the necessary info, though it is not
       designed to be machine parseable.

       Do NOT assume that each paths from Conflicted file info, and the
       logical conflicts in the Informational messages 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.

       Do NOT assume all filenames listed in the Informational messages
       section had conflicts. Messages can be included for files that have no
       conflicts, such as "Auto-merging <file>".

       AVOID taking the OIDS from the Conflicted file info 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 OID of
       toplevel tree 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 Conflicted file info and thus you would be losing information
       that might help the user resolve the conflict.

DEPRECATED DESCRIPTION
       Per the DESCRIPTION and unlike the rest of this documentation, this
       section describes the deprecated --trivial-merge mode.

       Other than the optional --trivial-merge, this mode accepts no options.

       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 <branch1>. The
       result of this second form is similar to what three-way git read-tree
       -m does, but instead of storing the results in the index, the command
       outputs the entries to the standard output.

       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).

GIT
       Part of the git(1) suite



Git 2.38.4			  05/16/2024		     GIT-MERGE-TREE(1)