Volume XXII, number 279Tuesday, October 6, 2026Latest message 46 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patch, 2 partsdoc: refs: put ref migration warning under the command

19 messages between Jul 31, 2026 and Aug 6, 2026, from kristofferhaugsbakk@fastmail.com, Junio C Hamano, Patrick Steinhardt, Kristoffer Haugsbakk, Karthik Nayak.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

kristofferhaugsbakk@fastmail.comJul 31, 2026, 09:07 UTC on lore
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
kristofferhaugsbakk@fastmail.comJul 31, 2026, 09:07 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +15 −14
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
kristofferhaugsbakk@fastmail.comJul 31, 2026, 09:07 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +1 −1
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
Junio C HamanoJul 31, 2026, 16:39 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

kristofferhaugsbakk@fastmail.com writes:
Show 6 quoted lines
> 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.
Patrick SteinhardtAug 4, 2026, 14:30 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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
Patrick SteinhardtAug 4, 2026, 14:30 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

On Fri, Jul 31, 2026 at 11:07:03AM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 17 quoted lines
> 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
Patrick SteinhardtAug 4, 2026, 14:30 UTC in reply to Junio C Hamano on lore

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

On Fri, Jul 31, 2026 at 09:39:42AM -0700, Junio C Hamano wrote:
Show 16 quoted lines
> 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
Kristoffer HaugsbakkAug 4, 2026, 19:09 UTC in reply to Patrick Steinhardt on lore

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

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.
Patrick SteinhardtAug 5, 2026, 08:07 UTC in reply to Kristoffer Haugsbakk on lore

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

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!
Show 5 quoted lines
> 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
Kristoffer HaugsbakkAug 5, 2026, 09:13 UTC in reply to Patrick Steinhardt on lore

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

On Wed, Aug 5, 2026, at 10:07, Patrick Steinhardt wrote:
Show 14 quoted lines
> 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.
kristofferhaugsbakk@fastmail.comAug 5, 2026, 19:02 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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:
Show changes to Documentation/git-refs.adoc +1 −1
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
kristofferhaugsbakk@fastmail.comAug 5, 2026, 19:02 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +15 −14
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
kristofferhaugsbakk@fastmail.comAug 5, 2026, 19:02 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +1 −1
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
Patrick SteinhardtAug 6, 2026, 05:15 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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
kristofferhaugsbakk@fastmail.comAug 6, 2026, 06:20 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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
kristofferhaugsbakk@fastmail.comAug 6, 2026, 06:20 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +15 −14
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
kristofferhaugsbakk@fastmail.comAug 6, 2026, 06:20 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

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(-)
Show changes to Documentation/git-refs.adoc +1 −1
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
Karthik NayakAug 6, 2026, 11:01 UTC in reply to kristofferhaugsbakk@fastmail.com on lore

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

kristofferhaugsbakk@fastmail.com writes:
Show 28 quoted lines
> 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!

Junio C HamanoAug 6, 2026, 17:32 UTC in reply to Patrick Steinhardt on lore

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

Patrick Steinhardt <ps@pks.im> writes:
Show 9 quoted lines
> 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.

Back to recent threads