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

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

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: doc-refs-migrate-limitations

Topic summary: Put ref migration warning as an admonition under the command
so that it is visible.

That’s the first patch. The second patch adds a missing `linkgit` since it
touches that same warning text.

I have two other patches that are not included here. They are unrelated
cleanups that I will post later. Here are the commit subjects and the first
paragraph so that you can see what they are about:

• doc: refs: wrap standalone placeholders in underscores

  This is a synopsis manpage which means that standalone placeholders[1]
  are supposed to use underscores (_), not backticks (`).[2]
• doc: refs: use inline-verbatim throughout

  Use inline-verbatim backticks (`) for literal commands, options, and
  subcommands listed under the “Commands” section.

§ Cc list

The two people that I have the impression that have worked most on
this command.

[1/2] doc: refs: put ref migration warning under the command
[2/2] doc: refs: linkgit to git-maintenance(1)

 Documentation/git-refs.adoc | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)


base-commit: 13c7afec212fc97ce257d15601659314c6673d6c
-- 
2.54.0.22.g9e26862b904

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

[kristofferhaugsbakk]

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.

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]
+--
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with git-maintenance(1).
+
+These limitations may eventually be lifted.
+--
 
 `verify`::
 	Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
 	Operate on <ref> itself rather than the reference it points to via a
 	symbolic ref.
 
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.54.0.22.g9e26862b904

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

[Patrick Steinhardt]

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

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

[Kristoffer Haugsbakk]

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: <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.

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

[Patrick Steinhardt]

On Tue, Aug 04, 2026 at 09:09:25PM +0200, Kristoffer Haugsbakk wrote:
> On Tue, Aug 4, 2026, at 16:30, Patrick Steinhardt wrote:
[snip]
> This is just an informational note and not an argument for using this
> particular construct.

Thanks for the explanation!

> 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/

Hm, interesting. According to the docs, WARNING is to instruct the user
of any lingering danger, whereas CAUTION asks them to act carefully. And
while the first bullet point is merely a limitation (we cannot migrate
worktrees), the second bullet point is indeed a warning that concurrent
writers may cause harm. So going by that I think that a WARNING would
indeed be a better fit.

Patrick

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

[Kristoffer Haugsbakk]

On Wed, Aug 5, 2026, at 10:07, Patrick Steinhardt wrote:
> On Tue, Aug 04, 2026 at 09:09:25PM +0200, Kristoffer Haugsbakk wrote:
>[snip]
>> 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/
>
> Hm, interesting. According to the docs, WARNING is to instruct the user
> of any lingering danger, whereas CAUTION asks them to act carefully. And
> while the first bullet point is merely a limitation (we cannot migrate
> worktrees), the second bullet point is indeed a warning that concurrent
> writers may cause harm. So going by that I think that a WARNING would
> indeed be a better fit.

Thanks. I’ll use Warning in the next version.

[PATCH 2/2] doc: refs: linkgit to git-maintenance(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-refs.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 98828041c23..1ec26be0b4f 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:
   ongoing migration. Concurrent writes can lead to an inconsistent migrated
   state. Users are expected to block writes on a higher level. If your
   repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
+  unregister it first with linkgit:git-maintenance[1].
 
 These limitations may eventually be lifted.
 --
-- 
2.54.0.22.g9e26862b904

Re: [PATCH 2/2] doc: refs: linkgit to git-maintenance(1)

[Patrick Steinhardt]

On Fri, Jul 31, 2026 at 11:07:03AM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-refs.adoc | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
> index 98828041c23..1ec26be0b4f 100644
> --- a/Documentation/git-refs.adoc
> +++ b/Documentation/git-refs.adoc
> @@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:
>    ongoing migration. Concurrent writes can lead to an inconsistent migrated
>    state. Users are expected to block writes on a higher level. If your
>    repository is registered for scheduled maintenance, it is recommended to
> -  unregister it first with git-maintenance(1).
> +  unregister it first with linkgit:git-maintenance[1].

Makes sense.

Patrick

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

[Junio C Hamano]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Topic name: doc-refs-migrate-limitations
>
> Topic summary: Put ref migration warning as an admonition under the command
> so that it is visible.

The caveat only applies to the "migrate" subcommand, and the new
placement gives us a much better logical organization.

> That’s the first patch. The second patch adds a missing `linkgit` since it
> touches that same warning text.

Looks good.  Thanks.

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

[Patrick Steinhardt]

On Fri, Jul 31, 2026 at 09:39:42AM -0700, Junio C Hamano wrote:
> kristofferhaugsbakk@fastmail.com writes:
> 
> > From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> >
> > Topic name: doc-refs-migrate-limitations
> >
> > Topic summary: Put ref migration warning as an admonition under the command
> > so that it is visible.
> 
> The caveat only applies to the "migrate" subcommand, and the new
> placement gives us a much better logical organization.
> 
> > That’s the first patch. The second patch adds a missing `linkgit` since it
> > touches that same warning text.
> 
> Looks good.  Thanks.

Both patches look good to me. The indentation feels one level too deep
on the firstr patch, but this is a tiny nitpick that we may not even
want to address in the first place.

Thanks!

Patrick

[PATCH v2 0/2] doc: refs: put ref migration warning under the command

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): doc-refs-migrate-limitations

Topic summary: Put ref migration warning as an admonition under the command
so that it is visible.

That’s the first patch. The second patch adds a missing `linkgit` since it
touches that same warning text.

I have two other patches that are not included here. They are unrelated
cleanups that I will post later. Here are the commit subjects and the first
paragraph so that you can see what they are about:

• doc: refs: wrap standalone placeholders in underscores

  This is a synopsis manpage which means that standalone placeholders[1]
  are supposed to use underscores (_), not backticks (`).[2]
• doc: refs: use inline-verbatim throughout

  Use inline-verbatim backticks (`) for literal commands, options, and
  subcommands listed under the “Commands” section.

§ Cc list

The two people that I have the impression that have worked most on
this command.

§ Changes in v2

• Patch 1/2: Use Warning admonition instead of Caution
• Patch 2/2: Add Ack

§ Link to v1

https://lore.kernel.org/git/CV_git_ref_migration_warning.b09@msgid.xyz/

[1/2] doc: refs: put ref migration warning under the command
[2/2] doc: refs: linkgit to git-maintenance(1)

 Documentation/git-refs.adoc | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

Interdiff against v1:
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 1ec26be0b4f..9063892651e 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -36,7 +36,7 @@ COMMANDS
 `migrate`::
 	Migrate ref store between different formats.
 +
-[CAUTION]
+[WARNING]
 --
 The ref format migration has several known limitations in its current form:
 
Range-diff against v1:
1:  cc4d9ca5006 ! 1:  8a6415e2d9b doc: refs: put ref migration warning under the command
    @@ Commit message
         `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.
    +    up to the command description and put it inside a Warning 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
    @@ Documentation/git-refs.adoc: COMMANDS
      `migrate`::
      	Migrate ref store between different formats.
     ++
    -+[CAUTION]
    ++[WARNING]
     +--
     +The ref format migration has several known limitations in its current form:
     +
2:  7265de45c9d ! 2:  801a3d7f539 doc: refs: linkgit to git-maintenance(1)
    @@ Metadata
      ## Commit message ##
         doc: refs: linkgit to git-maintenance(1)
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-refs.adoc ##

base-commit: 13c7afec212fc97ce257d15601659314c6673d6c
-- 
2.54.0.22.g9e26862b904

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

[kristofferhaugsbakk]

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 Warning 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.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2: use Warning admonition instead of Caution[1]
        🔗 1: https://lore.kernel.org/git/anLvVAyckm7S9Vo0@pks.im/

 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..3b5af936ed6 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -35,6 +35,21 @@ COMMANDS
 
 `migrate`::
 	Migrate ref store between different formats.
++
+[WARNING]
+--
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with git-maintenance(1).
+
+These limitations may eventually be lifted.
+--
 
 `verify`::
 	Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
 	Operate on <ref> itself rather than the reference it points to via a
 	symbolic ref.
 
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.54.0.22.g9e26862b904

[PATCH v2 2/2] doc: refs: linkgit to git-maintenance(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2: add Ack from previous round

 Documentation/git-refs.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 3b5af936ed6..9063892651e 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:
   ongoing migration. Concurrent writes can lead to an inconsistent migrated
   state. Users are expected to block writes on a higher level. If your
   repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
+  unregister it first with linkgit:git-maintenance[1].
 
 These limitations may eventually be lifted.
 --
-- 
2.54.0.22.g9e26862b904

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

[Patrick Steinhardt]

On Wed, Aug 05, 2026 at 09:02:34PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> § Changes in v2
> 
> • Patch 1/2: Use Warning admonition instead of Caution
> • Patch 2/2: Add Ack

Thanks, I'm happy with this version!

Patrick

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

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> On Wed, Aug 05, 2026 at 09:02:34PM +0200, kristofferhaugsbakk@fastmail.com wrote:
>> § Changes in v2
>> 
>> • Patch 1/2: Use Warning admonition instead of Caution
>> • Patch 2/2: Add Ack
>
> Thanks, I'm happy with this version!
>
> Patrick

Thanks, both.  Let me mark the topic for 'next', then.

[PATCH v3 0/2] doc: refs: put ref migration warning under the command

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name (applied): doc-refs-migrate-limitations

Topic summary: Put ref migration warning as an admonition under the command
so that it is visible.

That’s the first patch. The second patch adds a missing `linkgit` since it
touches that same warning text.

I have two other patches that are not included here. They are unrelated
cleanups that I will post later. Here are the commit subjects and the first
paragraph so that you can see what they are about:

• doc: refs: wrap standalone placeholders in underscores

  This is a synopsis manpage which means that standalone placeholders[1]
  are supposed to use underscores (_), not backticks (`).[2]
• doc: refs: use inline-verbatim throughout

  Use inline-verbatim backticks (`) for literal commands, options, and
  subcommands listed under the “Commands” section.

§ Cc list

The two people that I have the impression that have worked most on
this command.

§ Changes in v3

• Patch 1/2: Add Ack

§ Link to v2

https://lore.kernel.org/git/V2_CV_git_ref_migration_warning.b20@msgid.xyz/

[1/2] doc: refs: put ref migration warning under the command
[2/2] doc: refs: linkgit to git-maintenance(1)

 Documentation/git-refs.adoc | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

Interdiff against v2:
Range-diff against v2:
1:  8a6415e2d9b ! 1:  3ea1680afc8 doc: refs: put ref migration warning under the command
    @@ Commit message
         description. A one-page man page. But that is not the case anymore
         now that the command has nine subcommands to describe.
     
    +    Acked-by: Patrick Steinhardt <ps@pks.im>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/git-refs.adoc ##
2:  801a3d7f539 = 2:  1d91be5762b doc: refs: linkgit to git-maintenance(1)

base-commit: 13c7afec212fc97ce257d15601659314c6673d6c
-- 
2.54.0.22.g9e26862b904

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

[kristofferhaugsbakk]

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 Warning 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.

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v3: add Ack from previous round
    v2: use Warning admonition instead of Caution[1]
        🔗 1: https://lore.kernel.org/git/anLvVAyckm7S9Vo0@pks.im/

 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..3b5af936ed6 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -35,6 +35,21 @@ COMMANDS
 
 `migrate`::
 	Migrate ref store between different formats.
++
+[WARNING]
+--
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with git-maintenance(1).
+
+These limitations may eventually be lifted.
+--
 
 `verify`::
 	Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
 	Operate on <ref> itself rather than the reference it points to via a
 	symbolic ref.
 
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.54.0.22.g9e26862b904

[PATCH v3 2/2] doc: refs: linkgit to git-maintenance(1)

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2: add Ack from previous round

 Documentation/git-refs.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 3b5af936ed6..9063892651e 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:
   ongoing migration. Concurrent writes can lead to an inconsistent migrated
   state. Users are expected to block writes on a higher level. If your
   repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
+  unregister it first with linkgit:git-maintenance[1].
 
 These limitations may eventually be lifted.
 --
-- 
2.54.0.22.g9e26862b904

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

[Karthik Nayak]

[-- Attachment #1: Type: text/plain, Size: 1182 bytes --]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> Topic name (applied): doc-refs-migrate-limitations
>
> Topic summary: Put ref migration warning as an admonition under the command
> so that it is visible.
>
> That’s the first patch. The second patch adds a missing `linkgit` since it
> touches that same warning text.
>
> I have two other patches that are not included here. They are unrelated
> cleanups that I will post later. Here are the commit subjects and the first
> paragraph so that you can see what they are about:
>
> • doc: refs: wrap standalone placeholders in underscores
>
>   This is a synopsis manpage which means that standalone placeholders[1]
>   are supposed to use underscores (_), not backticks (`).[2]
> • doc: refs: use inline-verbatim throughout
>
>   Use inline-verbatim backticks (`) for literal commands, options, and
>   subcommands listed under the “Commands” section.
>
> § Cc list
>
> The two people that I have the impression that have worked most on
> this command.
>

Sorry for the late review, been a bit busy. The two patches look good to
me! Thanks!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]