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

[Patrick Steinhardt <ps@pks.im>]

On Fri, Jul 31, 2026 at 11:07:02AM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> I have to scroll down at least three screens in man(1) from the
> `migrate` description in order to see the “known limitations” for
> it. This is important information since the text says that concurrent
> writes can lead to an inconsistent migrated state. Let’s move that text
> up to the command description and put it inside a Caution admonition.
> 
> This section made sense when it was added in 25a0023f (builtin/refs:
> new command to migrate ref storage formats, 2024-06-06); `migrate` was
> the only subcommand, and this section was visible from the command
> description. A one-page man page. But that is not the case anymore
> now that the command has nine subcommands to describe.

That feels quite sensible indeed.

> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-refs.adoc | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
> 
> 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.

Patrick