Re: [PATCH 1/2] doc: refs: put ref migration warning under the command

On Tue, Aug 4, 2026, at 16:30, Patrick Steinhardt wrote:
>>[snip]
>> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
>> index ce278c59bfc..98828041c23 100644
>> --- a/Documentation/git-refs.adoc
>> +++ b/Documentation/git-refs.adoc
>> @@ -35,6 +35,21 @@ COMMANDS
>>
>>  `migrate`::
>>  	Migrate ref store between different formats.
>> ++
>> +[CAUTION]
>> +--
>
> Hm, okay, first time I see this format. It feels like the rendered
> version is indented once level too deep, but I guess that's more of a
> problem with how asciidoc decides to process this. And it's a tiny nit
> only that may not even be worth addressing.

The admonition format is used in many places in the docs, but probably
mostly in the one-block/paragraph format:

    NOTE: <paragraph>

Not this this open-block syntax. (But see git-blame(1) for an open block
`NOTE` example.)

Like two times in git-clone(1). On that doc there is a contrast between
this markup and a `NOTE:` which is just that plain text. With just
`NOTE:`:

    This option ...

    NOTE: This operation ...

And with the markup (manpage):

    When the repository ...

        NOTE
        this is a possibly dangerous operation; ...

Or in HTML:

    When the repository ...

    NOTE | this is a possibly dangerous operation; ...
         | ...
         | ...

This is just an informational note and not an argument for using this
particular construct.

By the way, I think I looked at the AsciiDoc admonition reference[1] and
saw `CAUTION` and `WARNING`, but now I don’t recall why I chose Caution
over Warning.

🔗 1: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/

Thanks for taking a look.