diff options
Diffstat (limited to 'Documentation/git-merge-tree.txt')
| -rw-r--r-- | Documentation/git-merge-tree.txt | 103 |
1 files changed, 91 insertions, 12 deletions
diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index d6c3567..dd388fa 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -19,12 +19,12 @@ 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. +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 feature as the "real" +The performed merge will use the same features as the "real" linkgit:git-merge[1], including: * three way content merges of individual files @@ -64,6 +64,14 @@ OPTIONS share no common history. This flag can be given to override that check and make the merge proceed anyway. +--merge-base=<tree-ish>:: + 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`. ++ +As the merge-base is provided directly, <branch1> and <branch2> do not need +to specify commits; trees are enough. + [[OUTPUT]] OUTPUT ------ @@ -81,6 +89,31 @@ Whereas for a conflicted merge, the output is by default of the form: 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 ~~~~~~~~~~~~~~~~~~~~ @@ -108,18 +141,50 @@ 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: +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> (<reason>)" + * "Failed to merge submodule <submodule> (no merge base)" * "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. +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 ----------- @@ -127,7 +192,10 @@ 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). +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 ----------- @@ -156,6 +224,17 @@ with linkgit:git-merge[1]: * any messages that would have been printed to stdout (the <<IM,Informational messages>>) +INPUT FORMAT +------------ +'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 ----------------- @@ -177,7 +256,7 @@ 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 +files 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. @@ -187,7 +266,7 @@ 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 +Do NOT assume that each path 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 |