[GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge

From: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
Date: Feb 20, 2025, 15:12 UTC
Message-ID: <20250220151207.3248-1-lucasseikioshiro@gmail.com>

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@gmail.com>
Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
---

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)