From: Elijah Newren via GitGitGadget Date: Wed, 02 Feb 2022 07:34:41 GMT Subject: [PATCH v3 15/15] git-merge-tree.txt: add a section on potentional usage mistakes Message-ID: In-Reply-To: From: Elijah Newren Signed-off-by: Elijah Newren --- Documentation/git-merge-tree.txt | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index e6a9ff2768b..6a2ed475106 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -146,6 +146,52 @@ that they'd have access to if using `git merge`: * any messages that would have been printed to stdout (the ) +MISTAKES TO AVOID +----------------- + +Do NOT look through the resulting toplevel tree to try to find which +files conflict; parse the 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 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 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 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 + section has the necessary info, though it is +not designed to be machine parseable. + +Do NOT assume all filenames listed in the +section had conflicts. Messages can be included for files that have no +conflicts, such as "Auto-merging ". + +AVOID taking the OIDS from the 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 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 and thus you would be losing information that +might help the user resolve the conflict. + GIT --- Part of the linkgit:git[1] suite -- gitgitgadget