{"thread":{"id":"62982","subject":"[GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","startedAt":"2025-02-20T15:12:16Z","lastAt":"2025-02-24T17:31:47Z","messageCount":9,"participants":["Lucas Seiki Oshiro","D. Ben Knoble","Junio C Hamano","Jean-Noël Avila","Elijah Newren"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"512774","messageId":"20250220151207.3248-1-lucasseikioshiro@gmail.com","threadId":"62982","inReplyTo":null,"subject":"[GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Lucas Seiki Oshiro","fromEmail":"lucasseikioshiro@gmail.com","sentAt":"2025-02-20T15:12:07Z","receivedAt":"2025-02-20T15:12:16Z","isPatch":true,"sender":{"key":"lucasseikioshiro@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701580?v=4"},"body":"Submodule merges are, in general, similar to other merges based on oid\nthree-way-merge. When a conflict happens, however, Git has two special\ncases (introduced in 68d03e4a6e44) on handling the conflict before\nyielding it to the user. From the merge-ort and merge-recursive sources:\n\n- \"Case #1: a is contained in b or vice versa\": both strategies try to\nperform a fast-forward in the submodules if the commit referred by the\nconflicted submodule is descendant of another;\n\n- \"Case #2: There are one or more merges that contain a and b in the\nsubmodule. If there is only one, then present it as a suggestion to the\nuser, but leave it marked unmerged so the user needs to confirm the\nresolution.\"\n\nAdd a small paragraph on merge-strategies.adoc describing this behavior.\n\nHelped-by: Elijah Newren \nSigned-off-by: Lucas Seiki Oshiro \n---\n\nThis v2 changes the documentation text to a clearer explanation (as\nsuggested in the v1 review), and changes its location to\nmerge-strategies.adoc instead of git-merge.adoc.\n\nThis content is duplicated as this works for both `ort` and `recursive`\nstrategies.\n\n Documentation/merge-strategies.adoc | 15 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\nindex 5fc54ec060..a7fca249e2 100644\n--- a/Documentation/merge-strategies.adoc\n+++ b/Documentation/merge-strategies.adoc\n@@ -21,6 +21,13 @@ ort::\n \t(\"Ostensibly Recursive's Twin\") and came from the fact that it\n \twas written as a replacement for the previous default\n \talgorithm, `recursive`.\n+\n+ In the case where the path is a submodule, if the submodule commit\n+ used on one side of the merge is a descendant of the submodule\n+ commit used on the other side of the merge, Git attempts to\n+ fast-forward to the descendant. Otherwise, Git will treat this case\n+ as a conflict, suggesting as a resolution a submodule commit that\n+ is descendant of the conflicting ones, if one exists.\n +\n The 'ort' strategy can take the following options:\n \n@@ -95,6 +102,13 @@ recursive::\n \trenames. It does not make use of detected copies. This was\n \tthe default strategy for resolving two heads from Git v0.99.9k\n \tuntil v2.33.0.\n+\n+ In the case where the path is a submodule, if the submodule commit\n+ used on one side of the merge is a descendant of the submodule\n+ commit used on the other side of the merge, Git attempts to\n+ fast-forward to the descendant. Otherwise, Git will treat this case\n+ as a conflict, suggesting as a resolution a submodule commit that\n+ is descendant of the conflicting ones, if one exists.\n +\n The 'recursive' strategy takes the same options as 'ort'. However,\n there are three additional options that 'ort' ignores (not documented\n-- \n2.39.5 (Apple Git-154)\n\n"},{"id":"512781","messageId":"CALnO6CCiBkz=vrzMban86h7uAPZVXq=eLYtbQkffTg8WFJSCdQ@mail.gmail.com","threadId":"62982","inReplyTo":"20250220151207.3248-1-lucasseikioshiro@gmail.com","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-02-20T18:46:35Z","receivedAt":"2025-02-20T18:46:47Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Thu, Feb 20, 2025 at 10:14 AM Lucas Seiki Oshiro\n wrote:\n>\n> Submodule merges are, in general, similar to other merges based on oid\n> three-way-merge. When a conflict happens, however, Git has two special\n> cases (introduced in 68d03e4a6e44) on handling the conflict before\n> yielding it to the user. From the merge-ort and merge-recursive sources:\n>\n> - \"Case #1: a is contained in b or vice versa\": both strategies try to\n> perform a fast-forward in the submodules if the commit referred by the\n> conflicted submodule is descendant of another;\n>\n> - \"Case #2: There are one or more merges that contain a and b in the\n> submodule. If there is only one, then present it as a suggestion to the\n> user, but leave it marked unmerged so the user needs to confirm the\n> resolution.\"\n>\n> Add a small paragraph on merge-strategies.adoc describing this behavior.\n>\n> Helped-by: Elijah Newren \n> Signed-off-by: Lucas Seiki Oshiro \n> ---\n>\n> This v2 changes the documentation text to a clearer explanation (as\n> suggested in the v1 review), and changes its location to\n> merge-strategies.adoc instead of git-merge.adoc.\n\nThis version is clearer to me at least, thanks!\n\n>\n> This content is duplicated as this works for both `ort` and `recursive`\n> strategies.\n>\n> Documentation/merge-strategies.adoc | 15 ++++++++++++++\n> 1 file changed, 14 insertions(+)\n>\n> diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\n> index 5fc54ec060..a7fca249e2 100644\n> --- a/Documentation/merge-strategies.adoc\n> +++ b/Documentation/merge-strategies.adoc\n> @@ -21,6 +21,13 @@ ort::\n> (\"Ostensibly Recursive's Twin\") and came from the fact that it\n> was written as a replacement for the previous default\n> algorithm, `recursive`.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'ort' strategy can take the following options:\n>\n> @@ -95,6 +102,13 @@ recursive::\n> renames. It does not make use of detected copies. This was\n> the default strategy for resolving two heads from Git v0.99.9k\n> until v2.33.0.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n\nI'm not particularly a fan of duplicated documentation text: is there\na way to reuse one from the other or have one refer/link to the other?\n\n\n\n-- \nD. Ben Knoble\n"},{"id":"512782","messageId":"xmqqmsegctvx.fsf@gitster.g","threadId":"62982","inReplyTo":"20250220151207.3248-1-lucasseikioshiro@gmail.com","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-02-20T19:12:50Z","receivedAt":"2025-02-20T19:12:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lucas Seiki Oshiro writes:\n\n> Submodule merges are, in general, similar to other merges based on oid\n> three-way-merge. When a conflict happens, however, Git has two special\n> cases (introduced in 68d03e4a6e44) on handling the conflict before\n> yielding it to the user. From the merge-ort and merge-recursive sources:\n>\n> - \"Case #1: a is contained in b or vice versa\": both strategies try to\n> perform a fast-forward in the submodules if the commit referred by the\n> conflicted submodule is descendant of another;\n>\n> - \"Case #2: There are one or more merges that contain a and b in the\n> submodule. If there is only one, then present it as a suggestion to the\n> user, but leave it marked unmerged so the user needs to confirm the\n> resolution.\"\n>\n> Add a small paragraph on merge-strategies.adoc describing this behavior.\n>\n> Helped-by: Elijah Newren \n> Signed-off-by: Lucas Seiki Oshiro \n> ---\n>\n> This v2 changes the documentation text to a clearer explanation (as\n> suggested in the v1 review), and changes its location to\n> merge-strategies.adoc instead of git-merge.adoc.\n>\n> This content is duplicated as this works for both `ort` and `recursive`\n> strategies.\n>\n> Documentation/merge-strategies.adoc | 15 ++++++++++++++\n> 1 file changed, 14 insertions(+)\n>\n> diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\n> index 5fc54ec060..a7fca249e2 100644\n> --- a/Documentation/merge-strategies.adoc\n> +++ b/Documentation/merge-strategies.adoc\n> @@ -21,6 +21,13 @@ ort::\n> \t(\"Ostensibly Recursive's Twin\") and came from the fact that it\n> \twas written as a replacement for the previous default\n> \talgorithm, `recursive`.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'ort' strategy can take the following options:\n\nI am not going to comment on the text, but as to the formatting, I'd\npoint out that the existing\n\n +\n The 'ort' strategy can ...\n\nconstruct, i.e. a line with only '+' on it, followed by left-aligned\nblock of text, is how AsciiDoc wants our second and subsequent\nparagraphs for an enumerated list of explanations. Here, the\nexisting \"The 'ort' strategy can ...\" is the second paragraph that\nfollows the paragraph that ends with \"... previous default\nalgorithm, 'recursive'\", which is the explanation for the item with\n\"ort::\" heading.\n\nSo, you'd need to (1) change the empty line at the beginning of your\nadded text to have one '+' and nothing else on it, and (2) dedent\nthe rest of the text you added to abut the left edge of the page.\nDitto for the other hunk on \"recursive::\".\n\nThanks.\n"},{"id":"512819","messageId":"70b76a89-00a4-4ba6-92f2-4fb46981317d@free.fr","threadId":"62982","inReplyTo":"20250220151207.3248-1-lucasseikioshiro@gmail.com","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-02-21T10:17:41Z","receivedAt":"2025-02-21T10:27:32Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 20/02/2025 à 16:12, Lucas Seiki Oshiro a écrit :\n> Submodule merges are, in general, similar to other merges based on oid\n> three-way-merge. When a conflict happens, however, Git has two special\n> cases (introduced in 68d03e4a6e44) on handling the conflict before\n> yielding it to the user. From the merge-ort and merge-recursive sources:\n> \n> - \"Case #1: a is contained in b or vice versa\": both strategies try to\n> perform a fast-forward in the submodules if the commit referred by the\n> conflicted submodule is descendant of another;\n> \n> - \"Case #2: There are one or more merges that contain a and b in the\n> submodule. If there is only one, then present it as a suggestion to the\n> user, but leave it marked unmerged so the user needs to confirm the\n> resolution.\"\n> \n> Add a small paragraph on merge-strategies.adoc describing this behavior.\n> \n> Helped-by: Elijah Newren \n> Signed-off-by: Lucas Seiki Oshiro \n> ---\n> \n> This v2 changes the documentation text to a clearer explanation (as\n> suggested in the v1 review), and changes its location to\n> merge-strategies.adoc instead of git-merge.adoc.\n> \n> This content is duplicated as this works for both `ort` and `recursive`\n> strategies.\n> \n> Documentation/merge-strategies.adoc | 15 ++++++++++++++\n> 1 file changed, 14 insertions(+)\n> \n> diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\n> index 5fc54ec060..a7fca249e2 100644\n> --- a/Documentation/merge-strategies.adoc\n> +++ b/Documentation/merge-strategies.adoc\n> @@ -21,6 +21,13 @@ ort::\n> \t(\"Ostensibly Recursive's Twin\") and came from the fact that it\n> \twas written as a replacement for the previous default\n> \talgorithm, `recursive`.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'ort' strategy can take the following options:\n> \n> @@ -95,6 +102,13 @@ recursive::\n> \trenames. It does not make use of detected copies. This was\n> \tthe default strategy for resolving two heads from Git v0.99.9k\n> \tuntil v2.33.0.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'recursive' strategy takes the same options as 'ort'. However,\n> there are three additional options that 'ort' ignores (not documented\n\n\nIf both chunks are meant to be kept identical, I would recommend to\ndefine an attribute (see\nhttps://docs.asciidoctor.org/asciidoc/latest/attributes/custom-attributes/)\nand use it at both sites.\n\nThanks.\n\n"},{"id":"512840","messageId":"xmqqy0xz9nno.fsf@gitster.g","threadId":"62982","inReplyTo":"70b76a89-00a4-4ba6-92f2-4fb46981317d@free.fr","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-02-21T18:07:55Z","receivedAt":"2025-02-21T18:07:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël Avila writes:\n\n>> @@ -95,6 +102,13 @@ recursive::\n>> \trenames. It does not make use of detected copies. This was\n>> \tthe default strategy for resolving two heads from Git v0.99.9k\n>> \tuntil v2.33.0.\n>> +\n>> + In the case where the path is a submodule, if the submodule commit\n>> + used on one side of the merge is a descendant of the submodule\n>> + commit used on the other side of the merge, Git attempts to\n>> + fast-forward to the descendant. Otherwise, Git will treat this case\n>> + as a conflict, suggesting as a resolution a submodule commit that\n>> + is descendant of the conflicting ones, if one exists.\n>> +\n>> The 'recursive' strategy takes the same options as 'ort'. However,\n>> there are three additional options that 'ort' ignores (not documented\n>\n>\n> If both chunks are meant to be kept identical, I would recommend to\n> define an attribute (see\n> https://docs.asciidoctor.org/asciidoc/latest/attributes/custom-attributes/)\n> and use it at both sites.\n\nWouldn't it be a bit awkward to maintain a six-line paragraph as a\ncustom attribute, though [*1*]? Would the resulting text become\nlike (without indentation) this?\n\n :submodule-merge: \\\n In the case where the path is a submodule, if the submodule commit \\\n used on one side of the merge is a descendant of the submodule \\\n commit used on the other side of the merge, Git attempts to \\\n fast-forward to the descendant. Otherwise, Git will treat this case \\\n as a conflict, suggesting as a resolution a submodule commit that \\\n is descendant of the conflicting ones, if one exists.\n\n recursive::\n ...\n the default strategy for resolving two heads from Git v0.99.9k\n until v2.33.0.\n +\n {submodule-merge}\n +\n The 'recursive strategy takes the same options as ...\n\n\nJust as in C preprocessor macros in *.h files, I am reluctant to\nforce our people to edit long multi-line text while not forgetting\nto lose the backslash for line continuation (or misplace existing\nones when wrapping lines).\n\nAnd of course a 6-line paragraph is not large enough to put in a\nseparate file to be included.\n\nHmph...\n\nThanks.\n\n\n\n[Reference]\n\n*1* \nhttps://github.com/asciidoctor/asciidoctor/issues/1341#issuecomment-101841014\n"},{"id":"512863","messageId":"CABPp-BEDhJJW6+9SgRQKWmKGBANV8cmem1FXtrFKmYgmY7Ud8Q@mail.gmail.com","threadId":"62982","inReplyTo":"20250220151207.3248-1-lucasseikioshiro@gmail.com","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2025-02-21T21:56:17Z","receivedAt":"2025-02-21T21:56:28Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"Hi,\n\nOn Thu, Feb 20, 2025 at 7:12 AM Lucas Seiki Oshiro\n wrote:\n>\n> Submodule merges are, in general, similar to other merges based on oid\n> three-way-merge. When a conflict happens, however, Git has two special\n> cases (introduced in 68d03e4a6e44) on handling the conflict before\n> yielding it to the user. From the merge-ort and merge-recursive sources:\n>\n> - \"Case #1: a is contained in b or vice versa\": both strategies try to\n> perform a fast-forward in the submodules if the commit referred by the\n> conflicted submodule is descendant of another;\n>\n> - \"Case #2: There are one or more merges that contain a and b in the\n> submodule. If there is only one, then present it as a suggestion to the\n> user, but leave it marked unmerged so the user needs to confirm the\n> resolution.\"\n>\n> Add a small paragraph on merge-strategies.adoc describing this behavior.\n>\n> Helped-by: Elijah Newren \n> Signed-off-by: Lucas Seiki Oshiro \n> ---\n>\n> This v2 changes the documentation text to a clearer explanation (as\n> suggested in the v1 review), and changes its location to\n> merge-strategies.adoc instead of git-merge.adoc.\n>\n> This content is duplicated as this works for both `ort` and `recursive`\n> strategies.\n>\n> Documentation/merge-strategies.adoc | 15 ++++++++++++++\n> 1 file changed, 14 insertions(+)\n>\n> diff --git a/Documentation/merge-strategies.adoc b/Documentation/merge-strategies.adoc\n> index 5fc54ec060..a7fca249e2 100644\n> --- a/Documentation/merge-strategies.adoc\n> +++ b/Documentation/merge-strategies.adoc\n> @@ -21,6 +21,13 @@ ort::\n> (\"Ostensibly Recursive's Twin\") and came from the fact that it\n> was written as a replacement for the previous default\n> algorithm, `recursive`.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'ort' strategy can take the following options:\n>\n> @@ -95,6 +102,13 @@ recursive::\n> renames. It does not make use of detected copies. This was\n> the default strategy for resolving two heads from Git v0.99.9k\n> until v2.33.0.\n> +\n> + In the case where the path is a submodule, if the submodule commit\n> + used on one side of the merge is a descendant of the submodule\n> + commit used on the other side of the merge, Git attempts to\n> + fast-forward to the descendant. Otherwise, Git will treat this case\n> + as a conflict, suggesting as a resolution a submodule commit that\n> + is descendant of the conflicting ones, if one exists.\n> +\n> The 'recursive' strategy takes the same options as 'ort'. However,\n> there are three additional options that 'ort' ignores (not documented\n> --\n> 2.39.5 (Apple Git-154)\n\nSo, seeing it here, I note that these are meant a bit more as\nhigh-level overviews of the algorithms. I pushed you away from\nincluding this in git-merge.adoc because while that manual page does\ndive into merge resolution details, that manual page is specific to\nmerge. The information here pertains to merge as well as cherry-pick,\nrebase, revert, replay, merge-tree, etc.\n\nWe don't seem to have a place that is general for all\nmerge-machinery-using commands, and which also dives into details\nabout how merges are resolved.\n\nI don't have a good solution. I think it's probably fine to include\nhere in merge-strategies.adoc, even if it feels suboptimal and icky,\nsince any other current solution would be as well. But I would be\ninterested in the opinions of other reviewers on this point and\nwhether they see a good solution (short of completely overhauling all\nmerge-related documentation for any merge-using-command, which might\nbe a viable strategy but shouldn't hold up a small patch like this).\n"},{"id":"512875","messageId":"0256f214-795d-42a4-8319-4ba79777face@gmail.com","threadId":"62982","inReplyTo":"xmqqy0xz9nno.fsf@gitster.g","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Lucas Seiki Oshiro","fromEmail":"lucasseikioshiro@gmail.com","sentAt":"2025-02-22T19:36:26Z","receivedAt":"2025-02-22T19:36:31Z","isPatch":true,"sender":{"key":"lucasseikioshiro@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701580?v=4"},"body":"> And of course a 6-line paragraph is not large enough to put in a\n> separate file to be included.\n\nI'm a newbie here, so I can't have a strong opinion on what's\nthe best solution for managing those files. But, given that:\n\n1. `ort` will sometime replace `recursive`\n2. the last change in the content of this document was in\n f5a3c5e637, three years ago, basically copying the content\n from `recursive` to `ort`\n\nit looks like to me that creating another file only for this\nparagraph would harder to maintain than that duplication.\n\nI mean, if eventually `recursive` is replaced by `ort`, one\nwill need to remember to move this paragraph to\n`merge-strategies`, as it will be used only in the `ort`\ndocumentation. On the other hand, given that this document\nhaven't changed since the introduction of `ort`, this\nduplication doesn't seem to me that will be hard to be\nmanaged.\n\nAnyway, thanks for the feedback!\n"},{"id":"512876","messageId":"xmqqa5ad8vzf.fsf@gitster.g","threadId":"62982","inReplyTo":"0256f214-795d-42a4-8319-4ba79777face@gmail.com","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-02-22T22:17:56Z","receivedAt":"2025-02-22T22:17:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lucas Seiki Oshiro writes:\n\n>> And of course a 6-line paragraph is not large enough to put in a\n>> separate file to be included.\n>\n> I'm a newbie here, so I can't have a strong opinion on what's\n> the best solution for managing those files. But, given that:\n>\n> 1. `ort` will sometime replace `recursive`\n> 2. the last change in the content of this document was in\n> f5a3c5e637, three years ago, basically copying the content\n> from `recursive` to `ort`\n>\n> it looks like to me that creating another file only for this\n> paragraph would harder to maintain than that duplication.\n>\n> I mean, if eventually `recursive` is replaced by `ort`, one\n> will need to remember to move this paragraph to\n> `merge-strategies`, as it will be used only in the `ort`\n> documentation. On the other hand, given that this document\n> haven't changed since the introduction of `ort`, this\n> duplication doesn't seem to me that will be hard to be\n> managed.\n\nA relatively easy way out would be to have the full warning in the\n'ort' section, and then only add only something like\n\n\tFor a path that is a submodule, the same caution as 'ort'\n\tapplies to this strategy.\n\nto the 'recursive' section.\n"},{"id":"512923","messageId":"CALnO6CC+7fPjD5f_LZ1PFavdpKqAjMDmrFL8azwatYpS=+pODg@mail.gmail.com","threadId":"62982","inReplyTo":"xmqqa5ad8vzf.fsf@gitster.g","subject":"Re: [GSoC][PATCH v2] merge-strategies.adoc: detail submodule merge","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2025-02-24T17:31:34Z","receivedAt":"2025-02-24T17:31:47Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Sat, Feb 22, 2025 at 5:18 PM Junio C Hamano wrote:\n>\n> Lucas Seiki Oshiro writes:\n>\n> >> And of course a 6-line paragraph is not large enough to put in a\n> >> separate file to be included.\n> >\n> > I'm a newbie here, so I can't have a strong opinion on what's\n> > the best solution for managing those files. But, given that:\n> >\n> > 1. `ort` will sometime replace `recursive`\n> > 2. the last change in the content of this document was in\n> > f5a3c5e637, three years ago, basically copying the content\n> > from `recursive` to `ort`\n> >\n> > it looks like to me that creating another file only for this\n> > paragraph would harder to maintain than that duplication.\n> >\n> > I mean, if eventually `recursive` is replaced by `ort`, one\n> > will need to remember to move this paragraph to\n> > `merge-strategies`, as it will be used only in the `ort`\n> > documentation. On the other hand, given that this document\n> > haven't changed since the introduction of `ort`, this\n> > duplication doesn't seem to me that will be hard to be\n> > managed.\n>\n> A relatively easy way out would be to have the full warning in the\n> 'ort' section, and then only add only something like\n>\n> For a path that is a submodule, the same caution as 'ort'\n> applies to this strategy.\n>\n> to the 'recursive' section.\n\nIndeed, that seems preferable to me (based on a similar conversation\nabout a different documentation change in another project [1]).\n\n[1]: https://github.com/racket/racket/pull/5144#issuecomment-2563172012\n\n-- \nD. Ben Knoble\n"}]}