git-merge-tree(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT | EXIT STATUS | USAGE NOTES | INPUT FORMAT | MISTAKES TO AVOID | DEPRECATED DESCRIPTION | GIT | COLOPHON

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

NAME         top

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

SYNOPSIS         top

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

DESCRIPTION         top

       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 the 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 features as the "real"
       git-merge(1), including:

       •   three way content merges of individual files

       •   rename detection

       •   proper directory/file conflict handling

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

       •   etc.

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

OPTIONS         top

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

       --merge-base=<commit>
           Instead of finding the merge-bases for <branch1> and
           <branch2>, specify a merge-base for the merge, and specifying
           multiple bases is currently not supported. This option is
           incompatible with --stdin.

OUTPUT         top

       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.

       However, there is an exception. If --stdin 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:

           <Merge status>
           <OID of toplevel tree>
           <Conflicted file info>
           <Informational messages>
           NUL
           <Merge status>
           <OID of toplevel tree>
           NUL

   Merge status
       This is an integer status followed by a NUL character. The
       integer status is:

           0: merge had conflicts
           1: merge was clean
           <0: something prevented the merge from running (e.g. access to repository
               objects denied by filesystem)

   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 section provides informational messages, typically about
       conflicts. The format of the section varies significantly
       depending on whether -z is passed.

       If -z is passed:

       The output format is zero or more conflict informational records,
       each of the form:

           <list-of-paths><conflict-type>NUL<conflict-message>NUL

       where <list-of-paths> is of the form

           <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL

       and includes paths (or branch names) affected by the conflict or
       informational message in <conflict-message>. Also,
       <conflict-type> is a stable string explaining the type of
       conflict, such as

       •   "Auto-merging"

       •   "CONFLICT (rename/delete)"

       •   "CONFLICT (submodule lacks merge base)"

       •   "CONFLICT (binary)"

       and <conflict-message> is a more detailed message about the
       conflict which often (but not always) embeds the
       <stable-short-type-description> within it. These strings may
       change in future Git versions. Some examples:

       •   "Auto-merging <file>"

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

       •   "Failed to merge submodule <submodule> (no merge base)"

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

       If -z is NOT passed:

       This section starts with a blank line to separate it from the
       previous sections, and then only contains the <conflict-message>
       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 <conflict-message> 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.

EXIT STATUS         top

       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.

USAGE NOTES         top

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

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

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

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

INPUT FORMAT         top

       git merge-tree --stdin input format is fully text based. Each
       line has this format:

           [<base-commit> -- ]<branch1> <branch2>

       If one line is separated by --, 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.

MISTAKES TO AVOID         top

       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 files 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 path 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         top

       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         top

       Part of the git(1) suite

COLOPHON         top

       This page is part of the git (Git distributed version control
       system) project.  Information about the project can be found at
       ⟨http://git-scm.com/⟩.  If you have a bug report for this manual
       page, see ⟨http://git-scm.com/community⟩.  This page was obtained
       from the project's upstream Git repository
       ⟨https://github.com/git/git.git⟩ on 2023-12-22.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2023-12-20.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Git 2.43.0.174.g055bb6         2023-12-20              GIT-MERGE-TREE(1)

Pages that refer to this page: git(1)