[v5,12/12] git-merge-tree.txt: add a section on potentional usage mistakes

Commit Message

Elijah Newren Feb. 20, 2022, 6:54 a.m. UTC

From: Elijah Newren <[e-mail]>

Signed-off-by: Elijah Newren <[e-mail]>
---
 Documentation/git-merge-tree.txt | 46 ++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

Comments

Johannes Schindelin Feb. 22, 2022, 4:26 p.m. UTC | #1

Hi Elijah,

On Sun, 20 Feb 2022, Elijah Newren via GitGitGadget wrote:

> From: Elijah Newren <[e-mail]>
>
> Signed-off-by: Elijah Newren <[e-mail]>
> ---
>  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
>

Patch

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