From 7260e87248e743b197d34c1caf3949ae4fa3bc12 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Sat, 18 Jun 2022 00:21:00 +0000 Subject: [PATCH] git-merge-tree.txt: add a section on potentional usage mistakes Signed-off-by: Elijah Newren Signed-off-by: Junio C Hamano --- Documentation/git-merge-tree.txt | 53 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/Documentation/git-merge-tree.txt b/Documentation/git-merge-tree.txt index 628324646d..d6c356740e 100644 --- a/Documentation/git-merge-tree.txt +++ b/Documentation/git-merge-tree.txt @@ -156,6 +156,59 @@ with linkgit:git-merge[1]: * 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 that each paths from <>, and +the logical conflicts in the <> 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 +path can have many logical conflict types in a single merge, and each +logical conflict type can affect many paths. + +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. + [[DEPMERGE]] DEPRECATED DESCRIPTION ---------------------- -- 2.11.4.GIT