git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
KHKristoffer 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.
Previous: Patrick SteinhardtNext: Patrick Steinhardt
Message 4 of 19 in “doc: refs: put ref migration warning under the command”
  1. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Jul 31, 2026
  2. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Jul 31, 2026
  3. Patrick SteinhardtAug 4, 2026
  4. Kristoffer HaugsbakkAug 4, 2026
  5. Patrick SteinhardtAug 5, 2026
  6. Kristoffer HaugsbakkAug 5, 2026
  7. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Jul 31, 2026
  8. Patrick SteinhardtAug 4, 2026
  9. Junio C HamanoJul 31, 2026
  10. Patrick SteinhardtAug 4, 2026
  11. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 5, 2026
  12. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 5, 2026
  13. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Aug 5, 2026
  14. Patrick SteinhardtAug 6, 2026
  15. Junio C HamanoAug 6, 2026
  16. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 6, 2026
  17. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 6, 2026
  18. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Aug 6, 2026
  19. Karthik NayakAug 6, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.