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 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 git-merge.adoc describing this behavior. Signed-off-by: Lucas Seiki Oshiro <lucasseikioshiro@xxxxxxxxx> --- Hi, This is a "scratch-my-own-itch" documentation patch. Some years ago I was questioned why some submodule merges on GitHub lead to conflicts while locally they didn't. I only could find a answer for that reading the merge-ort source code, then a wrote a blog post about that, which you check here: https://lucasoshiro.github.io/posts-en/2022-03-12-merge-submodule/ Thus, this patch adds to the official documentation what I found at the time. I wasn't certain if this should belong to the submodule or merge documentation, so, by now, I'm sending it as a merge documentation patch. Documentation/git-merge.adoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/git-merge.adoc b/Documentation/git-merge.adoc index 64281d6d44..7b12c0d648 100644 --- a/Documentation/git-merge.adoc +++ b/Documentation/git-merge.adoc @@ -205,6 +205,13 @@ happens: same and the index entries for them stay as they were, i.e. matching `HEAD`. +In the case where the path is a submodule, if the commit referred by it in HEAD +is descendant of the one referred by it in MERGE_HEAD or vice-versa, Git +attempts to fast-forward to the descendant, when using `ort` or `recursive` +strategies. 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. + If you tried a merge which resulted in complex conflicts and want to start over, you can recover with `git merge --abort`. -- 2.39.5 (Apple Git-154)
