| Message ID | 20250225161800.8268-1-lucasseikioshiro@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [GSoC,v3] merge-strategies.adoc: detail submodule merge | expand |
Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes: > 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> > --- > > This v3 keeps the same content as the previous v2. However, it uses the > proper way to declare paragraphs inside explanations and replaces the > duplicated paragraph in `recursive` strategy by a small paragraph > telling that it behaves the same way as `ort` when merging submodules. > > Documentation/merge-strategies.adoc | 11 +++++++++++ > 1 file changed, 11 insertions(+) > > diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc > index 5fc54ec060..9c30f1c900 100644 > --- 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: OK. > @@ -95,6 +102,10 @@ 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. > + > ++ > +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 Should the blank line be added above '+'? I somehow doubt it. Other than that, looking very good. Thanks.
> Should the blank line be added above '+'? I somehow doubt it. To be honest, this is my first time using asciidoctor, I sincerely don't know. Building a local pdf with `asciidoctor-pdf` didn't change the generated PDF. But of course, this doesn't follow the style of the rest of the document. I'm sorry, I'll fix it in v4. > Other than that, looking very good. Thanks for your help in this patch!
diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc index 5fc54ec060..9c30f1c900 100644 --- 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;; @@ -95,6 +102,10 @@ 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. + ++ +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
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> --- This v3 keeps the same content as the previous v2. However, it uses the proper way to declare paragraphs inside explanations and replaces the duplicated paragraph in `recursive` strategy by a small paragraph telling that it behaves the same way as `ort` when merging submodules. Documentation/merge-strategies.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+)