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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 21, 2025, 18:07 UTC
Message-ID: <xmqqy0xz9nno.fsf@gitster.g>
In-Reply-To: <70b76a89-00a4-4ba6-92f2-4fb46981317d@free.fr>

Jean-Noël Avila <jn.avila@free.fr> writes:

Show 20 quoted lines

>> @@ -95,6 +102,13 @@ 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.
>> +
>> +        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 'recursive' strategy takes the same options as 'ort'.  However,
>>  there are three additional options that 'ort' ignores (not documented
>
>
> If both chunks are meant to be kept identical, I would recommend to
> define an attribute (see
> https://docs.asciidoctor.org/asciidoc/latest/attributes/custom-attributes/)
> and use it at both sites.

Wouldn't it be a bit awkward to maintain a six-line paragraph as a custom attribute, though [*1*]? Would the resulting text become like (without indentation) this?

  :submodule-merge: \
  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.

  recursive::
          ...
          the default strategy for resolving two heads from Git v0.99.9k
          until v2.33.0.
  +
  {submodule-merge}
  +
  The 'recursive strategy takes the same options as ...

Just as in C preprocessor macros in *.h files, I am reluctant to force our people to edit long multi-line text while not forgetting to lose the backslash for line continuation (or misplace existing ones when wrapping lines).

And of course a 6-line paragraph is not large enough to put in a separate file to be included.

Hmph...

Thanks.

[Reference]

*1* https://github.com/asciidoctor/asciidoctor/issues/1341#issuecomment-101841014