| 1 | git-merge-tree(1) |
| 2 | ================= |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-merge-tree - Perform merge without touching index or working tree |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [verse] |
| 12 | 'git merge-tree' [--write-tree] [<options>] <branch1> <branch2> |
| 13 | 'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated) |
| 14 | |
| 15 | [[NEWMERGE]] |
| 16 | DESCRIPTION |
| 17 | ----------- |
| 18 | |
| 19 | This command has a modern `--write-tree` mode and a deprecated |
| 20 | `--trivial-merge` mode. With the exception of the |
| 21 | <<DEPMERGE,DEPRECATED DESCRIPTION>> section at the end, the rest of |
| 22 | this documentation describes the modern `--write-tree` mode. |
| 23 | |
| 24 | Performs a merge, but does not make any new commits and does not read |
| 25 | from or write to either the working tree or index. |
| 26 | |
| 27 | The performed merge will use the same features as the "real" |
| 28 | linkgit:git-merge[1], including: |
| 29 | |
| 30 | * three way content merges of individual files |
| 31 | * rename detection |
| 32 | * proper directory/file conflict handling |
| 33 | * recursive ancestor consolidation (i.e. when there is more than one |
| 34 | merge base, creating a virtual merge base by merging the merge bases) |
| 35 | * etc. |
| 36 | |
| 37 | After the merge completes, a new toplevel tree object is created. See |
| 38 | `OUTPUT` below for details. |
| 39 | |
| 40 | OPTIONS |
| 41 | ------- |
| 42 | |
| 43 | --stdin:: |
| 44 | Read the commits to merge from the standard input rather than |
| 45 | the command-line. See <<INPUT,INPUT FORMAT>> below for more |
| 46 | information. Implies `-z`. |
| 47 | |
| 48 | -z:: |
| 49 | Do not quote filenames in the <Conflicted file info> section, |
| 50 | and end each filename with a NUL character rather than |
| 51 | newline. Also begin the messages section with a NUL character |
| 52 | instead of a newline. See <<OUTPUT,OUTPUT>> below for more |
| 53 | information. |
| 54 | |
| 55 | --name-only:: |
| 56 | In the Conflicted file info section, instead of writing a list |
| 57 | of (mode, oid, stage, path) tuples to output for conflicted |
| 58 | files, just provide a list of filenames with conflicts (and |
| 59 | do not list filenames multiple times if they have multiple |
| 60 | conflicting stages). |
| 61 | |
| 62 | --messages:: |
| 63 | --no-messages:: |
| 64 | Write any informational messages such as "Auto-merging <path>" |
| 65 | or CONFLICT notices to the end of stdout. If unspecified, the |
| 66 | default is to include these messages if there are merge |
| 67 | conflicts, and to omit them otherwise. |
| 68 | |
| 69 | --quiet:: |
| 70 | Disable all output from the program. Useful when you are only |
| 71 | interested in the exit status. Allows merge-tree to exit |
| 72 | early when it finds a conflict, and allows it to avoid writing |
| 73 | most objects created by merges. |
| 74 | |
| 75 | --allow-unrelated-histories:: |
| 76 | merge-tree will by default error out if the two branches specified |
| 77 | share no common history. This flag can be given to override that |
| 78 | check and make the merge proceed anyway. |
| 79 | |
| 80 | --merge-base=<tree-ish>:: |
| 81 | Instead of finding the merge-bases for <branch1> and <branch2>, |
| 82 | specify a merge-base for the merge. This option is incompatible with |
| 83 | `--stdin`. |
| 84 | + |
| 85 | Specifying multiple bases is currently not supported, which means that when |
| 86 | merging two branches with more than one merge-base, using this option may |
| 87 | cause merge results to differ from what `git merge` would compute. This |
| 88 | can include potentially losing some changes made on one side of the history |
| 89 | in the resulting merge. |
| 90 | + |
| 91 | With this option, since the merge-base is provided directly, <branch1> and |
| 92 | <branch2> do not need to specify commits; trees are enough. |
| 93 | |
| 94 | -X<option>:: |
| 95 | --strategy-option=<option>:: |
| 96 | Pass the merge strategy-specific option through to the merge strategy. |
| 97 | See linkgit:git-merge[1] for details. |
| 98 | |
| 99 | [[OUTPUT]] |
| 100 | OUTPUT |
| 101 | ------ |
| 102 | |
| 103 | For a successful merge, the output from git-merge-tree is simply one |
| 104 | line: |
| 105 | |
| 106 | <OID of toplevel tree> |
| 107 | |
| 108 | Whereas for a conflicted merge, the output is by default of the form: |
| 109 | |
| 110 | <OID of toplevel tree> |
| 111 | <Conflicted file info> |
| 112 | <Informational messages> |
| 113 | |
| 114 | These are discussed individually below. |
| 115 | |
| 116 | However, there is an exception. If `--stdin` is passed, then there is |
| 117 | an extra section at the beginning, a NUL character at the end, and then |
| 118 | all the sections repeat for each line of input. Thus, if the first merge |
| 119 | is conflicted and the second is clean, the output would be of the form: |
| 120 | |
| 121 | <Merge status> |
| 122 | <OID of toplevel tree> |
| 123 | <Conflicted file info> |
| 124 | <Informational messages> |
| 125 | NUL |
| 126 | <Merge status> |
| 127 | <OID of toplevel tree> |
| 128 | NUL |
| 129 | |
| 130 | [[MS]] |
| 131 | Merge status |
| 132 | ~~~~~~~~~~~~ |
| 133 | |
| 134 | This is an integer status followed by a NUL character. The integer status is: |
| 135 | |
| 136 | 0: merge had conflicts |
| 137 | 1: merge was clean |
| 138 | |
| 139 | [[OIDTLT]] |
| 140 | OID of toplevel tree |
| 141 | ~~~~~~~~~~~~~~~~~~~~ |
| 142 | |
| 143 | This is a tree object that represents what would be checked out in the |
| 144 | working tree at the end of `git merge`. If there were conflicts, then |
| 145 | files within this tree may have embedded conflict markers. This section |
| 146 | is always followed by a newline (or NUL if `-z` is passed). |
| 147 | |
| 148 | [[CFI]] |
| 149 | Conflicted file info |
| 150 | ~~~~~~~~~~~~~~~~~~~~ |
| 151 | |
| 152 | This is a sequence of lines with the format |
| 153 | |
| 154 | <mode> <object> <stage> <filename> |
| 155 | |
| 156 | The filename will be quoted as explained for the configuration |
| 157 | variable `core.quotePath` (see linkgit:git-config[1]). However, if |
| 158 | the `--name-only` option is passed, the mode, object, and stage will |
| 159 | be omitted. If `-z` is passed, the "lines" are terminated by a NUL |
| 160 | character instead of a newline character. |
| 161 | |
| 162 | [[IM]] |
| 163 | Informational messages |
| 164 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 165 | |
| 166 | This section provides informational messages, typically about |
| 167 | conflicts. The format of the section varies significantly depending |
| 168 | on whether `-z` is passed. |
| 169 | |
| 170 | If `-z` is passed: |
| 171 | |
| 172 | The output format is zero or more conflict informational records, each |
| 173 | of the form: |
| 174 | |
| 175 | <list-of-paths><conflict-type>NUL<conflict-message>NUL |
| 176 | |
| 177 | where <list-of-paths> is of the form |
| 178 | |
| 179 | <number-of-paths>NUL<path1>NUL<path2>NUL...<pathN>NUL |
| 180 | |
| 181 | and includes paths (or branch names) affected by the conflict or |
| 182 | informational message in <conflict-message>. Also, <conflict-type> is a |
| 183 | stable string explaining the type of conflict, such as |
| 184 | |
| 185 | * "Auto-merging" |
| 186 | * "CONFLICT (rename/delete)" |
| 187 | * "CONFLICT (submodule lacks merge base)" |
| 188 | * "CONFLICT (binary)" |
| 189 | |
| 190 | and <conflict-message> is a more detailed message about the conflict which often |
| 191 | (but not always) embeds the <stable-short-type-description> within it. These |
| 192 | strings may change in future Git versions. Some examples: |
| 193 | |
| 194 | * "Auto-merging <file>" |
| 195 | * "CONFLICT (rename/delete): <oldfile> renamed...but deleted in..." |
| 196 | * "Failed to merge submodule <submodule> (no merge base)" |
| 197 | * "Warning: cannot merge binary files: <filename>" |
| 198 | |
| 199 | If `-z` is NOT passed: |
| 200 | |
| 201 | This section starts with a blank line to separate it from the previous |
| 202 | sections, and then only contains the <conflict-message> information |
| 203 | from the previous section (separated by newlines). These are |
| 204 | non-stable strings that should not be parsed by scripts, and are just |
| 205 | meant for human consumption. Also, note that while <conflict-message> |
| 206 | strings usually do not contain embedded newlines, they sometimes do. |
| 207 | (However, the free-form messages will never have an embedded NUL |
| 208 | character). So, the entire block of information is meant for human |
| 209 | readers as an agglomeration of all conflict messages. |
| 210 | |
| 211 | EXIT STATUS |
| 212 | ----------- |
| 213 | |
| 214 | For a successful, non-conflicted merge, the exit status is 0. When the |
| 215 | merge has conflicts, the exit status is 1. If the merge is not able to |
| 216 | complete (or start) due to some kind of error, the exit status is |
| 217 | something other than 0 or 1 (and the output is unspecified). When |
| 218 | --stdin is passed, the return status is 0 for both successful and |
| 219 | conflicted merges, and something other than 0 or 1 if it cannot complete |
| 220 | all the requested merges. |
| 221 | |
| 222 | USAGE NOTES |
| 223 | ----------- |
| 224 | |
| 225 | This command is intended as low-level plumbing, similar to |
| 226 | linkgit:git-hash-object[1], linkgit:git-mktree[1], |
| 227 | linkgit:git-commit-tree[1], linkgit:git-write-tree[1], |
| 228 | linkgit:git-update-ref[1], and linkgit:git-mktag[1]. Thus, it can be |
| 229 | used as a part of a series of steps such as: |
| 230 | |
| 231 | vi message.txt |
| 232 | BRANCH1=refs/heads/test |
| 233 | BRANCH2=main |
| 234 | NEWTREE=$(git merge-tree --write-tree $BRANCH1 $BRANCH2) || { |
| 235 | echo "There were conflicts..." 1>&2 |
| 236 | exit 1 |
| 237 | } |
| 238 | NEWCOMMIT=$(git commit-tree $NEWTREE -F message.txt \ |
| 239 | -p $BRANCH1 -p $BRANCH2) |
| 240 | git update-ref $BRANCH1 $NEWCOMMIT |
| 241 | |
| 242 | Note that when the exit status is non-zero, `NEWTREE` in this sequence |
| 243 | will contain a lot more output than just a tree. |
| 244 | |
| 245 | For conflicts, the output includes the same information that you'd get |
| 246 | with linkgit:git-merge[1]: |
| 247 | |
| 248 | * what would be written to the working tree (the |
| 249 | <<OIDTLT,OID of toplevel tree>>) |
| 250 | * the higher order stages that would be written to the index (the |
| 251 | <<CFI,Conflicted file info>>) |
| 252 | * any messages that would have been printed to stdout (the |
| 253 | <<IM,Informational messages>>) |
| 254 | |
| 255 | [[INPUT]] |
| 256 | INPUT FORMAT |
| 257 | ------------ |
| 258 | 'git merge-tree --stdin' input format is fully text based. Each line |
| 259 | has this format: |
| 260 | |
| 261 | [<base-commit> -- ]<branch1> <branch2> |
| 262 | |
| 263 | If one line is separated by `--`, the string before the separator is |
| 264 | used for specifying a merge-base for the merge and the string after |
| 265 | the separator describes the branches to be merged. |
| 266 | |
| 267 | MISTAKES TO AVOID |
| 268 | ----------------- |
| 269 | |
| 270 | Do NOT look through the resulting toplevel tree to try to find which |
| 271 | files conflict; parse the <<CFI,Conflicted file info>> section instead. |
| 272 | Not only would parsing an entire tree be horrendously slow in large |
| 273 | repositories, there are numerous types of conflicts not representable by |
| 274 | conflict markers (modify/delete, mode conflict, binary file changed on |
| 275 | both sides, file/directory conflicts, various rename conflict |
| 276 | permutations, etc.) |
| 277 | |
| 278 | Do NOT interpret an empty <<CFI,Conflicted file info>> list as a clean |
| 279 | merge; check the exit status. A merge can have conflicts without having |
| 280 | individual files conflict (there are a few types of directory rename |
| 281 | conflicts that fall into this category, and others might also be added |
| 282 | in the future). |
| 283 | |
| 284 | Do NOT attempt to guess or make the user guess the conflict types from |
| 285 | the <<CFI,Conflicted file info>> list. The information there is |
| 286 | insufficient to do so. For example: Rename/rename(1to2) conflicts (both |
| 287 | sides renamed the same file differently) will result in three different |
| 288 | files having higher order stages (but each only has one higher order |
| 289 | stage), with no way (short of the <<IM,Informational messages>> section) |
| 290 | to determine which three files are related. File/directory conflicts |
| 291 | also result in a file with exactly one higher order stage. |
| 292 | Possibly-involved-in-directory-rename conflicts (when |
| 293 | "merge.directoryRenames" is unset or set to "conflicts") also result in |
| 294 | a file with exactly one higher order stage. In all cases, the |
| 295 | <<IM,Informational messages>> section has the necessary info, though it |
| 296 | is not designed to be machine parseable. |
| 297 | |
| 298 | Do NOT assume that each path from <<CFI,Conflicted file info>>, and |
| 299 | the logical conflicts in the <<IM,Informational messages>> have a |
| 300 | one-to-one mapping, nor that there is a one-to-many mapping, nor a |
| 301 | many-to-one mapping. Many-to-many mappings exist, meaning that each |
| 302 | path can have many logical conflict types in a single merge, and each |
| 303 | logical conflict type can affect many paths. |
| 304 | |
| 305 | Do NOT assume all filenames listed in the <<IM,Informational messages>> |
| 306 | section had conflicts. Messages can be included for files that have no |
| 307 | conflicts, such as "Auto-merging <file>". |
| 308 | |
| 309 | AVOID taking the OIDS from the <<CFI,Conflicted file info>> and |
| 310 | re-merging them to present the conflicts to the user. This will lose |
| 311 | information. Instead, look up the version of the file found within the |
| 312 | <<OIDTLT,OID of toplevel tree>> and show that instead. In particular, |
| 313 | the latter will have conflict markers annotated with the original |
| 314 | branch/commit being merged and, if renames were involved, the original |
| 315 | filename. While you could include the original branch/commit in the |
| 316 | conflict marker annotations when re-merging, the original filename is |
| 317 | not available from the <<CFI,Conflicted file info>> and thus you would |
| 318 | be losing information that might help the user resolve the conflict. |
| 319 | |
| 320 | [[DEPMERGE]] |
| 321 | DEPRECATED DESCRIPTION |
| 322 | ---------------------- |
| 323 | |
| 324 | Per the <<NEWMERGE,DESCRIPTION>> and unlike the rest of this |
| 325 | documentation, this section describes the deprecated `--trivial-merge` |
| 326 | mode. |
| 327 | |
| 328 | Other than the optional `--trivial-merge`, this mode accepts no |
| 329 | options. |
| 330 | |
| 331 | This mode reads three tree-ish, and outputs trivial merge results and |
| 332 | conflicting stages to the standard output in a semi-diff format. |
| 333 | Since this was designed for higher level scripts to consume and merge |
| 334 | the results back into the index, it omits entries that match |
| 335 | <branch1>. The result of this second form is similar to what |
| 336 | three-way 'git read-tree -m' does, but instead of storing the results |
| 337 | in the index, the command outputs the entries to the standard output. |
| 338 | |
| 339 | This form not only has limited applicability (a trivial merge cannot |
| 340 | handle content merges of individual files, rename detection, proper |
| 341 | directory/file conflict handling, etc.), the output format is also |
| 342 | difficult to work with, and it will generally be less performant than |
| 343 | the first form even on successful merges (especially if working in |
| 344 | large repositories). |
| 345 | |
| 346 | GIT |
| 347 | --- |
| 348 | Part of the linkgit:git[1] suite |