Hi Elijah, On Sun, 20 Feb 2022, Elijah Newren via GitGitGadget wrote: > From: Elijah Newren <newren@xxxxxxxxx> > > Signed-off-by: Elijah Newren <newren@xxxxxxxxx> > --- > Documentation/git-merge-tree.txt | 46 ++++++++++++++++++++++++++++++++ > 1 file changed, 46 insertions(+) Thank you for this. It addresses the concern I had about printing out the tree object ID in the conflicted case. Thanks, Dscho > > diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt > index d2ff2fa3035..306149fa0e2 100644 > --- a/Documentation/git-merge-tree.txt > +++ b/Documentation/git-merge-tree.txt > @@ -158,6 +158,52 @@ that they'd have access to if using `git merge`: > * any messages that would have been printed to stdout (the <Informational > messages>) > > +MISTAKES TO AVOID > +----------------- > + > +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 file > +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 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. > + > GIT > --- > Part of the linkgit:git[1] suite > -- > gitgitgadget >
