ec1edbcb56
Add an option, --stdin, to merge-tree which will accept lines of input with two branches to merge per line, and which will perform all the merges and give output for each in turn. This option implies -z, and modifies the output to also include a merge status since the exit code of the program can no longer convey that information now that multiple merges are involved. This could be useful, for example, by Git hosting providers. When one branch is updated, one may want to check whether all code reviews targetting that branch can still cleanly merge. Avoiding the overhead of starting up a separate process for each of those code reviews might provide significant savings in a repository with many code reviews. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
301 lines
11 KiB
Plaintext
301 lines
11 KiB
Plaintext
git-merge-tree(1)
|
|
=================
|
|
|
|
NAME
|
|
----
|
|
git-merge-tree - Perform merge without touching index or working tree
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git merge-tree' [--write-tree] [<options>] <branch1> <branch2>
|
|
'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated)
|
|
|
|
[[NEWMERGE]]
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
This command has a modern `--write-tree` mode and a deprecated
|
|
`--trivial-merge` mode. With the exception of the
|
|
<<DEPMERGE,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"
|
|
linkgit: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
|
|
-------
|
|
|
|
-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 <<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]]
|
|
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.
|
|
|
|
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
|
|
|
|
[[MS]]
|
|
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)
|
|
|
|
[[OIDTLT]]
|
|
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).
|
|
|
|
[[CFI]]
|
|
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 linkgit: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.
|
|
|
|
[[IM]]
|
|
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
|
|
-----------
|
|
|
|
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
|
|
-----------
|
|
|
|
This command is intended as low-level plumbing, similar to
|
|
linkgit:git-hash-object[1], linkgit:git-mktree[1],
|
|
linkgit:git-commit-tree[1], linkgit:git-write-tree[1],
|
|
linkgit:git-update-ref[1], and linkgit: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 linkgit:git-merge[1]:
|
|
|
|
* what would be written to the working tree (the
|
|
<<OIDTLT,OID of toplevel tree>>)
|
|
* the higher order stages that would be written to the index (the
|
|
<<CFI,Conflicted file info>>)
|
|
* any messages that would have been printed to stdout (the
|
|
<<IM,Informational messages>>)
|
|
|
|
MISTAKES TO AVOID
|
|
-----------------
|
|
|
|
Do NOT look through the resulting toplevel tree to try to find which
|
|
files conflict; parse the <<CFI,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 <<CFI,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 <<CFI,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 <<IM,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
|
|
<<IM,Informational messages>> section has the necessary info, though it
|
|
is not designed to be machine parseable.
|
|
|
|
Do NOT assume that each paths from <<CFI,Conflicted file info>>, and
|
|
the logical conflicts in the <<IM,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 <<IM,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 <<CFI,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
|
|
<<OIDTLT,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 <<CFI,Conflicted file info>> and thus you would
|
|
be losing information that might help the user resolve the conflict.
|
|
|
|
[[DEPMERGE]]
|
|
DEPRECATED DESCRIPTION
|
|
----------------------
|
|
|
|
Per the <<NEWMERGE,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 linkgit:git[1] suite
|