Hi,
On Thu, Feb 20, 2025 at 7:12 AM Lucas Seiki Oshiro
<lucasseikioshiro@xxxxxxxxx> wrote:
>
> Submodule merges are, in general, similar to other merges based on oid
> three-way-merge. When a conflict happens, however, Git has two special
> cases (introduced in 68d03e4a6e44) on handling the conflict before
> yielding it to the user. From the merge-ort and merge-recursive sources:
>
> - "Case #1: a is contained in b or vice versa": both strategies try to
> perform a fast-forward in the submodules if the commit referred by the
> conflicted submodule is descendant of another;
>
> - "Case #2: There are one or more merges that contain a and b in the
> submodule. If there is only one, then present it as a suggestion to the
> user, but leave it marked unmerged so the user needs to confirm the
> resolution."
>
> Add a small paragraph on merge-strategies.adoc describing this behavior.
>
> Helped-by: Elijah Newren <newren@xxxxxxxxx>
> Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx>
> ---
>
> This v2 changes the documentation text to a clearer explanation (as
> suggested in the v1 review), and changes its location to
> merge-strategies.adoc instead of git-merge.adoc.
>
> This content is duplicated as this works for both `ort` and `recursive`
> strategies.
>
> Documentation/merge-strategies.adoc | 15 ++++++++++++++
> 1 file changed, 14 insertions(+)
>
> diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc
> index 5fc54ec060..a7fca249e2 100644
> --- a/Documentation/merge-strategies.adoc
> +++ b/Documentation/merge-strategies.adoc
> @@ -21,6 +21,13 @@ ort::
> ("Ostensibly Recursive's Twin") and came from the fact that it
> was written as a replacement for the previous default
> algorithm, `recursive`.
> +
> + In the case where the path is a submodule, if the submodule commit
> + used on one side of the merge is a descendant of the submodule
> + commit used on the other side of the merge, Git attempts to
> + fast-forward to the descendant. Otherwise, Git will treat this case
> + as a conflict, suggesting as a resolution a submodule commit that
> + is descendant of the conflicting ones, if one exists.
> +
> The 'ort' strategy can take the following options:
>
> @@ -95,6 +102,13 @@ recursive::
> renames. It does not make use of detected copies. This was
> the default strategy for resolving two heads from Git v0.99.9k
> until v2.33.0.
> +
> + In the case where the path is a submodule, if the submodule commit
> + used on one side of the merge is a descendant of the submodule
> + commit used on the other side of the merge, Git attempts to
> + fast-forward to the descendant. Otherwise, Git will treat this case
> + as a conflict, suggesting as a resolution a submodule commit that
> + is descendant of the conflicting ones, if one exists.
> +
> The 'recursive' strategy takes the same options as 'ort'. However,
> there are three additional options that 'ort' ignores (not documented
> --
> 2.39.5 (Apple Git-154)
So, seeing it here, I note that these are meant a bit more as
high-level overviews of the algorithms. I pushed you away from
including this in git-merge.adoc because while that manual page does
dive into merge resolution details, that manual page is specific to
merge. The information here pertains to merge as well as cherry-pick,
rebase, revert, replay, merge-tree, etc.
We don't seem to have a place that is general for all
merge-machinery-using commands, and which also dives into details
about how merges are resolved.
I don't have a good solution. I think it's probably fine to include
here in merge-strategies.adoc, even if it feels suboptimal and icky,
since any other current solution would be as well. But I would be
interested in the opinions of other reviewers on this point and
whether they see a good solution (short of completely overhauling all
merge-related documentation for any merge-using-command, which might
be a viable strategy but shouldn't hold up a small patch like this).
