Re: [PATCH 1/2] doc: refs: put ref migration warning under the command
- From
- Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
- Date
- Aug 4, 2026, 19:09 UTC
- Message-ID
- <7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com>
- In-Reply-To
- <anH3k9PvWHMpWLT_@pks.im>
On Tue, Aug 4, 2026, at 16:30, Patrick Steinhardt wrote:
Show 17 quoted lines
>>[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.