# [PATCH 0/2] doc: refs: put ref migration warning under the command 19 messages from 2026-07-31 to 2026-08-06. Participants: kristofferhaugsbakk@fastmail.com, Junio C Hamano, Patrick Steinhardt, Kristoffer Haugsbakk, Karthik Nayak. Thread: https://gitlist.dev/t/66093 ## kristofferhaugsbakk@fastmail.com, 2026-07-31 09:07 Subject: [PATCH 0/2] doc: refs: put ref migration warning under the command Message-ID: ``` From: Kristoffer Haugsbakk 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.com, 2026-07-31 09:07 Subject: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk 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 --- 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 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.com, 2026-07-31 09:07 Subject: [PATCH 2/2] doc: refs: linkgit to git-maintenance(1) Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk Signed-off-by: Kristoffer Haugsbakk --- 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 ``` ## Junio C Hamano, 2026-07-31 16:39 Subject: Re: [PATCH 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` kristofferhaugsbakk@fastmail.com writes: > From: Kristoffer Haugsbakk > > 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 Steinhardt, 2026-08-04 14:30 Subject: Re: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` On Fri, Jul 31, 2026 at 11:07:02AM +0200, kristofferhaugsbakk@fastmail.com wrote: > From: Kristoffer Haugsbakk > > 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 > --- > 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 Steinhardt, 2026-08-04 14:30 Subject: Re: [PATCH 2/2] doc: refs: linkgit to git-maintenance(1) Message-ID: In-Reply-To: ``` On Fri, Jul 31, 2026 at 11:07:03AM +0200, kristofferhaugsbakk@fastmail.com wrote: > From: Kristoffer Haugsbakk > > Signed-off-by: Kristoffer Haugsbakk > --- > 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 Steinhardt, 2026-08-04 14:30 Subject: Re: [PATCH 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` On Fri, Jul 31, 2026 at 09:39:42AM -0700, Junio C Hamano wrote: > kristofferhaugsbakk@fastmail.com writes: > > > From: Kristoffer Haugsbakk > > > > 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 Haugsbakk, 2026-08-04 19:09 Subject: Re: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: <7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com> In-Reply-To: ``` 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: 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 Steinhardt, 2026-08-05 08:07 Subject: Re: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: <7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com> ``` 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 ``` ## Kristoffer Haugsbakk, 2026-08-05 09:13 Subject: Re: [PATCH 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` 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. ``` ## kristofferhaugsbakk@fastmail.com, 2026-08-05 19:02 Subject: [PATCH v2 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk 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 Signed-off-by: Kristoffer Haugsbakk ## Documentation/git-refs.adoc ## base-commit: 13c7afec212fc97ce257d15601659314c6673d6c -- 2.54.0.22.g9e26862b904 ``` ## kristofferhaugsbakk@fastmail.com, 2026-08-05 19:02 Subject: [PATCH v2 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk 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 --- 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 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.com, 2026-08-05 19:02 Subject: [PATCH v2 2/2] doc: refs: linkgit to git-maintenance(1) Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk Acked-by: Patrick Steinhardt Signed-off-by: Kristoffer Haugsbakk --- 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 ``` ## Patrick Steinhardt, 2026-08-06 05:15 Subject: Re: [PATCH v2 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` 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.com, 2026-08-06 06:20 Subject: [PATCH v3 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk 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 Signed-off-by: Kristoffer Haugsbakk ## 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.com, 2026-08-06 06:20 Subject: [PATCH v3 1/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk 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 Signed-off-by: Kristoffer Haugsbakk --- 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 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.com, 2026-08-06 06:20 Subject: [PATCH v3 2/2] doc: refs: linkgit to git-maintenance(1) Message-ID: In-Reply-To: ``` From: Kristoffer Haugsbakk Acked-by: Patrick Steinhardt Signed-off-by: Kristoffer Haugsbakk --- 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 ``` ## Karthik Nayak, 2026-08-06 11:01 Subject: Re: [PATCH v3 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` kristofferhaugsbakk@fastmail.com writes: > From: Kristoffer Haugsbakk > > 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 Hamano, 2026-08-06 17:32 Subject: Re: [PATCH v2 0/2] doc: refs: put ref migration warning under the command Message-ID: In-Reply-To: ``` Patrick Steinhardt 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. ```