From: Kristoffer Haugsbakk Date: Tue, 04 Aug 2026 19:09:25 GMT Subject: Re: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: <7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com> In-Reply-To: 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: 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.