merge-strategies.adoc: detail submodule merge

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: Junio C Hamano <gitster@pobox.com>
Helped-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc
index a5dc95a37838f56caa325681b2c80de64d67924a..93822ebc4e83b0abf10583d822a8d40bd50b86d7 100644 (file)
--- a/Documentation/merge-strategies.adoc
+++ b/Documentation/merge-strategies.adoc
@@ -22,6 +22,13 @@ ort::
        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:
 
 ours;;
@@ -96,6 +103,9 @@ recursive::
        the default strategy for resolving two heads from Git v0.99.9k
        until v2.33.0.
 +
+For a path that is a submodule, the same caution as 'ort' applies to this
+strategy.
++
 The 'recursive' strategy takes the same options as 'ort'.  However,
 there are three additional options that 'ort' ignores (not documented
 above) that are potentially useful with the 'recursive' strategy: