Re: [PATCH 1/2] doc: refs: put ref migration warning under the command
- From
Patrick Steinhardt <ps@pks.im>
- Date
- Aug 4, 2026, 14:30 UTC
- Message-ID
- <anH3k9PvWHMpWLT_@pks.im>
- In-Reply-To
- <ref_migration_warning.b0a@msgid.xyz>
On Fri, Jul 31, 2026 at 11:07:02AM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 13 quoted lines
> 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.
Show 16 quoted lines
> 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