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

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi Elijah,

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

> From: Elijah Newren <newren@gmail.com>
>
> Signed-off-by: Elijah Newren <newren@gmail.com>
> ---
>  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
>