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

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

[Lucas Seiki Oshiro]

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:
 
 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
-- 
2.39.5 (Apple Git-154)

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

[Junio C Hamano]

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.

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

[Lucas Seiki Oshiro]

> 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!