On 2022.02.02 07:34, Elijah Newren via GitGitGadget wrote: > diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt > index 58731c19422..569485815a0 100644 > --- a/Documentation/git-merge-tree.txt > +++ b/Documentation/git-merge-tree.txt > @@ -3,26 +3,73 @@ git-merge-tree(1) > > NAME > ---- > -git-merge-tree - Show three-way merge without touching index > +git-merge-tree - Perform merge without touching index or working tree > > > SYNOPSIS > -------- > [verse] > -'git merge-tree' <base-tree> <branch1> <branch2> > +'git merge-tree' [--write-tree] <branch1> <branch2> > +'git merge-tree' [--trivial-merge] <base-tree> <branch1> <branch2> (deprecated) > > DESCRIPTION > ----------- > -Reads three tree-ish, and output trivial merge results and > -conflicting stages to the standard output. This 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 is meant to be used by higher level scripts to compute > -merge results outside of the index, and stuff the results back into the > -index. For this reason, the output from the command omits > -entries that match the <branch1> tree. > + > +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 second form is deprecated and supported only for backward > +compatibility. It will likely be removed in the future, and will not > +be discussed further in this manual. > + > +The first form will merge the two branches, doing a real merge. A real > +merge is distinguished from a trivial merge in that it includes: > + > + * 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, it will create a new toplevel tree object. > +See `OUTPUT` below for details. > + > +OUTPUT > +------ > + > +For either a successful or conflicted merge, the output from > +git-merge-tree is simply one line: > + > + <OID of toplevel tree> > + > +The printed tree object corresponds to what would be checked out in > +the working tree at the end of `git merge`, and thus may have files > +with conflict markers in them. > + > +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. > + > +USAGE NOTES > +----------- > + > +git-merge-tree was written to be low-level plumbing, similar to > +hash-object, mktree, commit-tree, update-ref, and mktag. Thus, it could > +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 > + > +However, it does not quite fit into the same category of low-level > +plumbing commands since the possibility of merge conflicts give it a > +much higher chance of the command not succeeding. I found this final paragraph confusing. It seems to be hinting at some conclusion it expects readers to make, but I haven't been able to figure out what. Could this be made more explicit, or perhaps dropped altogether?
