{"thread":{"id":"66093","subject":"[PATCH 0/2] doc: refs: put ref migration warning under the command","startedAt":"2026-07-31T09:07:15Z","lastAt":"2026-08-06T17:32:21Z","messageCount":19,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","Patrick Steinhardt","Kristoffer Haugsbakk","Karthik Nayak"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"549337","messageId":"CV_git_ref_migration_warning.b09@msgid.xyz","threadId":"66093","inReplyTo":null,"subject":"[PATCH 0/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-31T09:07:01Z","receivedAt":"2026-07-31T09:07:15Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name: doc-refs-migrate-limitations\n\nTopic summary: Put ref migration warning as an admonition under the command\nso that it is visible.\n\nThat’s the first patch. The second patch adds a missing `linkgit` since it\ntouches that same warning text.\n\nI have two other patches that are not included here. They are unrelated\ncleanups that I will post later. Here are the commit subjects and the first\nparagraph so that you can see what they are about:\n\n• doc: refs: wrap standalone placeholders in underscores\n\n This is a synopsis manpage which means that standalone placeholders[1]\n are supposed to use underscores (_), not backticks (`).[2]\n• doc: refs: use inline-verbatim throughout\n\n Use inline-verbatim backticks (`) for literal commands, options, and\n subcommands listed under the “Commands” section.\n\n§ Cc list\n\nThe two people that I have the impression that have worked most on\nthis command.\n\n[1/2] doc: refs: put ref migration warning under the command\n[2/2] doc: refs: linkgit to git-maintenance(1)\n\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\n\nbase-commit: 13c7afec212fc97ce257d15601659314c6673d6c\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549338","messageId":"ref_migration_warning.b0a@msgid.xyz","threadId":"66093","inReplyTo":"CV_git_ref_migration_warning.b09@msgid.xyz","subject":"[PATCH 1/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-31T09:07:02Z","receivedAt":"2026-07-31T09:07:34Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nI have to scroll down at least three screens in man(1) from the\n`migrate` description in order to see the “known limitations” for\nit. This is important information since the text says that concurrent\nwrites can lead to an inconsistent migrated state. Let’s move that text\nup to the command description and put it inside a Caution admonition.\n\nThis section made sense when it was added in 25a0023f (builtin/refs:\nnew command to migrate ref storage formats, 2024-06-06); `migrate` was\nthe only subcommand, and this section was visible from the command\ndescription. A one-page man page. But that is not the case anymore\nnow that the command has nine subcommands to describe.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex ce278c59bfc..98828041c23 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -35,6 +35,21 @@ COMMANDS\n \n `migrate`::\n \tMigrate ref store between different formats.\n++\n+[CAUTION]\n+--\n+The ref format migration has several known limitations in its current form:\n+\n+* It is not possible to migrate repositories that have worktrees.\n+\n+* There is no way to block concurrent writes to the repository during an\n+ ongoing migration. Concurrent writes can lead to an inconsistent migrated\n+ state. Users are expected to block writes on a higher level. If your\n+ repository is registered for scheduled maintenance, it is recommended to\n+ unregister it first with git-maintenance(1).\n+\n+These limitations may eventually be lifted.\n+--\n \n `verify`::\n \tVerify reference database consistency.\n@@ -130,21 +145,6 @@ The following options are specific to commands which write references:\n \tOperate on itself rather than the reference it points to via a\n \tsymbolic ref.\n \n-KNOWN LIMITATIONS\n------------------\n-\n-The ref format migration has several known limitations in its current form:\n-\n-* It is not possible to migrate repositories that have worktrees.\n-\n-* There is no way to block concurrent writes to the repository during an\n- ongoing migration. Concurrent writes can lead to an inconsistent migrated\n- state. Users are expected to block writes on a higher level. If your\n- repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n-\n-These limitations may eventually be lifted.\n-\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549339","messageId":"linkgit_maintenance.b0b@msgid.xyz","threadId":"66093","inReplyTo":"CV_git_ref_migration_warning.b09@msgid.xyz","subject":"[PATCH 2/2] doc: refs: linkgit to git-maintenance(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-07-31T09:07:03Z","receivedAt":"2026-07-31T09:07:51Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-refs.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 98828041c23..1ec26be0b4f 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:\n ongoing migration. Concurrent writes can lead to an inconsistent migrated\n state. Users are expected to block writes on a higher level. If your\n repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n+ unregister it first with linkgit:git-maintenance[1].\n \n These limitations may eventually be lifted.\n --\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549359","messageId":"xmqqbjbncdv5.fsf@gitster.g","threadId":"66093","inReplyTo":"CV_git_ref_migration_warning.b09@msgid.xyz","subject":"Re: [PATCH 0/2] doc: refs: put ref migration warning under the command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-07-31T16:39:42Z","receivedAt":"2026-07-31T16:39:44Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Topic name: doc-refs-migrate-limitations\n>\n> Topic summary: Put ref migration warning as an admonition under the command\n> so that it is visible.\n\nThe caveat only applies to the \"migrate\" subcommand, and the new\nplacement gives us a much better logical organization.\n\n> That’s the first patch. The second patch adds a missing `linkgit` since it\n> touches that same warning text.\n\nLooks good. Thanks.\n"},{"id":"549570","messageId":"anH3k9PvWHMpWLT_@pks.im","threadId":"66093","inReplyTo":"ref_migration_warning.b0a@msgid.xyz","subject":"Re: [PATCH 1/2] doc: refs: put ref migration warning under the command","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-04T14:30:43Z","receivedAt":"2026-08-04T14:30:56Z","isPatch":true,"body":"On Fri, Jul 31, 2026 at 11:07:02AM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n> \n> I have to scroll down at least three screens in man(1) from the\n> `migrate` description in order to see the “known limitations” for\n> it. This is important information since the text says that concurrent\n> writes can lead to an inconsistent migrated state. Let’s move that text\n> up to the command description and put it inside a Caution admonition.\n> \n> This section made sense when it was added in 25a0023f (builtin/refs:\n> new command to migrate ref storage formats, 2024-06-06); `migrate` was\n> the only subcommand, and this section was visible from the command\n> description. A one-page man page. But that is not the case anymore\n> now that the command has nine subcommands to describe.\n\nThat feels quite sensible indeed.\n\n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n> 1 file changed, 15 insertions(+), 15 deletions(-)\n> \n> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\n> index ce278c59bfc..98828041c23 100644\n> --- a/Documentation/git-refs.adoc\n> +++ b/Documentation/git-refs.adoc\n> @@ -35,6 +35,21 @@ COMMANDS\n> \n> `migrate`::\n> \tMigrate ref store between different formats.\n> ++\n> +[CAUTION]\n> +--\n\nHm, okay, first time I see this format. It feels like the rendered\nversion is indented once level too deep, but I guess that's more of a\nproblem with how asciidoc decides to process this. And it's a tiny nit\nonly that may not even be worth addressing.\n\nPatrick\n"},{"id":"549571","messageId":"anH3mkk6K5RPMZlJ@pks.im","threadId":"66093","inReplyTo":"linkgit_maintenance.b0b@msgid.xyz","subject":"Re: [PATCH 2/2] doc: refs: linkgit to git-maintenance(1)","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-04T14:30:50Z","receivedAt":"2026-08-04T14:30:59Z","isPatch":true,"body":"On Fri, Jul 31, 2026 at 11:07:03AM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n> \n> Signed-off-by: Kristoffer Haugsbakk \n> ---\n> Documentation/git-refs.adoc | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\n> index 98828041c23..1ec26be0b4f 100644\n> --- a/Documentation/git-refs.adoc\n> +++ b/Documentation/git-refs.adoc\n> @@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:\n> ongoing migration. Concurrent writes can lead to an inconsistent migrated\n> state. Users are expected to block writes on a higher level. If your\n> repository is registered for scheduled maintenance, it is recommended to\n> - unregister it first with git-maintenance(1).\n> + unregister it first with linkgit:git-maintenance[1].\n\nMakes sense.\n\nPatrick\n"},{"id":"549572","messageId":"anH3oN3JRaG1eEfK@pks.im","threadId":"66093","inReplyTo":"xmqqbjbncdv5.fsf@gitster.g","subject":"Re: [PATCH 0/2] doc: refs: put ref migration warning under the command","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-04T14:30:56Z","receivedAt":"2026-08-04T14:31:06Z","isPatch":true,"body":"On Fri, Jul 31, 2026 at 09:39:42AM -0700, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n> \n> > From: Kristoffer Haugsbakk \n> >\n> > Topic name: doc-refs-migrate-limitations\n> >\n> > Topic summary: Put ref migration warning as an admonition under the command\n> > so that it is visible.\n> \n> The caveat only applies to the \"migrate\" subcommand, and the new\n> placement gives us a much better logical organization.\n> \n> > That’s the first patch. The second patch adds a missing `linkgit` since it\n> > touches that same warning text.\n> \n> Looks good. Thanks.\n\nBoth patches look good to me. The indentation feels one level too deep\non the firstr patch, but this is a tiny nitpick that we may not even\nwant to address in the first place.\n\nThanks!\n\nPatrick\n"},{"id":"549605","messageId":"7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com","threadId":"66093","inReplyTo":"anH3k9PvWHMpWLT_@pks.im","subject":"Re: [PATCH 1/2] doc: refs: put ref migration warning under the command","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-04T19:09:25Z","receivedAt":"2026-08-04T19:09:54Z","isPatch":true,"body":"On Tue, Aug 4, 2026, at 16:30, Patrick Steinhardt wrote:\n>>[snip]\n>> diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\n>> index ce278c59bfc..98828041c23 100644\n>> --- a/Documentation/git-refs.adoc\n>> +++ b/Documentation/git-refs.adoc\n>> @@ -35,6 +35,21 @@ COMMANDS\n>>\n>> `migrate`::\n>> \tMigrate ref store between different formats.\n>> ++\n>> +[CAUTION]\n>> +--\n>\n> Hm, okay, first time I see this format. It feels like the rendered\n> version is indented once level too deep, but I guess that's more of a\n> problem with how asciidoc decides to process this. And it's a tiny nit\n> only that may not even be worth addressing.\n\nThe admonition format is used in many places in the docs, but probably\nmostly in the one-block/paragraph format:\n\n NOTE: \n\nNot this this open-block syntax. (But see git-blame(1) for an open block\n`NOTE` example.)\n\nLike two times in git-clone(1). On that doc there is a contrast between\nthis markup and a `NOTE:` which is just that plain text. With just\n`NOTE:`:\n\n This option ...\n\n NOTE: This operation ...\n\nAnd with the markup (manpage):\n\n When the repository ...\n\n NOTE\n this is a possibly dangerous operation; ...\n\nOr in HTML:\n\n When the repository ...\n\n NOTE | this is a possibly dangerous operation; ...\n | ...\n | ...\n\nThis is just an informational note and not an argument for using this\nparticular construct.\n\nBy the way, I think I looked at the AsciiDoc admonition reference[1] and\nsaw `CAUTION` and `WARNING`, but now I don’t recall why I chose Caution\nover Warning.\n\n🔗 1: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/\n\nThanks for taking a look.\n"},{"id":"549658","messageId":"anLvVAyckm7S9Vo0@pks.im","threadId":"66093","inReplyTo":"7f34d9b6-de00-44c5-a59c-11f154e7a64a@app.fastmail.com","subject":"Re: [PATCH 1/2] doc: refs: put ref migration warning under the command","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-05T08:07:48Z","receivedAt":"2026-08-05T08:08:01Z","isPatch":true,"body":"On Tue, Aug 04, 2026 at 09:09:25PM +0200, Kristoffer Haugsbakk wrote:\n> On Tue, Aug 4, 2026, at 16:30, Patrick Steinhardt wrote:\n[snip]\n> This is just an informational note and not an argument for using this\n> particular construct.\n\nThanks for the explanation!\n\n> By the way, I think I looked at the AsciiDoc admonition reference[1] and\n> saw `CAUTION` and `WARNING`, but now I don’t recall why I chose Caution\n> over Warning.\n> \n> 🔗 1: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/\n\nHm, interesting. According to the docs, WARNING is to instruct the user\nof any lingering danger, whereas CAUTION asks them to act carefully. And\nwhile the first bullet point is merely a limitation (we cannot migrate\nworktrees), the second bullet point is indeed a warning that concurrent\nwriters may cause harm. So going by that I think that a WARNING would\nindeed be a better fit.\n\nPatrick\n"},{"id":"549663","messageId":"ef423f09-11dd-452b-9459-1baf017cde6f@app.fastmail.com","threadId":"66093","inReplyTo":"anLvVAyckm7S9Vo0@pks.im","subject":"Re: [PATCH 1/2] doc: refs: put ref migration warning under the command","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-05T09:13:15Z","receivedAt":"2026-08-05T09:13:41Z","isPatch":true,"body":"On Wed, Aug 5, 2026, at 10:07, Patrick Steinhardt wrote:\n> On Tue, Aug 04, 2026 at 09:09:25PM +0200, Kristoffer Haugsbakk wrote:\n>[snip]\n>> By the way, I think I looked at the AsciiDoc admonition reference[1] and\n>> saw `CAUTION` and `WARNING`, but now I don’t recall why I chose Caution\n>> over Warning.\n>>\n>> 🔗 1: https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/\n>\n> Hm, interesting. According to the docs, WARNING is to instruct the user\n> of any lingering danger, whereas CAUTION asks them to act carefully. And\n> while the first bullet point is merely a limitation (we cannot migrate\n> worktrees), the second bullet point is indeed a warning that concurrent\n> writers may cause harm. So going by that I think that a WARNING would\n> indeed be a better fit.\n\nThanks. I’ll use Warning in the next version.\n"},{"id":"549766","messageId":"V2_CV_git_ref_migration_warning.b20@msgid.xyz","threadId":"66093","inReplyTo":"CV_git_ref_migration_warning.b09@msgid.xyz","subject":"[PATCH v2 0/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-05T19:02:34Z","receivedAt":"2026-08-05T19:03:06Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): doc-refs-migrate-limitations\n\nTopic summary: Put ref migration warning as an admonition under the command\nso that it is visible.\n\nThat’s the first patch. The second patch adds a missing `linkgit` since it\ntouches that same warning text.\n\nI have two other patches that are not included here. They are unrelated\ncleanups that I will post later. Here are the commit subjects and the first\nparagraph so that you can see what they are about:\n\n• doc: refs: wrap standalone placeholders in underscores\n\n This is a synopsis manpage which means that standalone placeholders[1]\n are supposed to use underscores (_), not backticks (`).[2]\n• doc: refs: use inline-verbatim throughout\n\n Use inline-verbatim backticks (`) for literal commands, options, and\n subcommands listed under the “Commands” section.\n\n§ Cc list\n\nThe two people that I have the impression that have worked most on\nthis command.\n\n§ Changes in v2\n\n• Patch 1/2: Use Warning admonition instead of Caution\n• Patch 2/2: Add Ack\n\n§ Link to v1\n\nhttps://lore.kernel.org/git/CV_git_ref_migration_warning.b09@msgid.xyz/\n\n[1/2] doc: refs: put ref migration warning under the command\n[2/2] doc: refs: linkgit to git-maintenance(1)\n\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 1ec26be0b4f..9063892651e 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -36,7 +36,7 @@ COMMANDS\n `migrate`::\n \tMigrate ref store between different formats.\n +\n-[CAUTION]\n+[WARNING]\n --\n The ref format migration has several known limitations in its current form:\n \nRange-diff against v1:\n1: cc4d9ca5006 ! 1: 8a6415e2d9b doc: refs: put ref migration warning under the command\n @@ Commit message\n `migrate` description in order to see the “known limitations” for\n it. This is important information since the text says that concurrent\n writes can lead to an inconsistent migrated state. Let’s move that text\n - up to the command description and put it inside a Caution admonition.\n + up to the command description and put it inside a Warning admonition.\n \n This section made sense when it was added in 25a0023f (builtin/refs:\n new command to migrate ref storage formats, 2024-06-06); `migrate` was\n @@ Documentation/git-refs.adoc: COMMANDS\n `migrate`::\n \tMigrate ref store between different formats.\n ++\n -+[CAUTION]\n ++[WARNING]\n +--\n +The ref format migration has several known limitations in its current form:\n +\n2: 7265de45c9d ! 2: 801a3d7f539 doc: refs: linkgit to git-maintenance(1)\n @@ Metadata\n ## Commit message ##\n doc: refs: linkgit to git-maintenance(1)\n \n + Acked-by: Patrick Steinhardt \n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-refs.adoc ##\n\nbase-commit: 13c7afec212fc97ce257d15601659314c6673d6c\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549767","messageId":"V2_ref_migration_warning.b21@msgid.xyz","threadId":"66093","inReplyTo":"V2_CV_git_ref_migration_warning.b20@msgid.xyz","subject":"[PATCH v2 1/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-05T19:02:35Z","receivedAt":"2026-08-05T19:03:25Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nI have to scroll down at least three screens in man(1) from the\n`migrate` description in order to see the “known limitations” for\nit. This is important information since the text says that concurrent\nwrites can lead to an inconsistent migrated state. Let’s move that text\nup to the command description and put it inside a Warning admonition.\n\nThis section made sense when it was added in 25a0023f (builtin/refs:\nnew command to migrate ref storage formats, 2024-06-06); `migrate` was\nthe only subcommand, and this section was visible from the command\ndescription. A one-page man page. But that is not the case anymore\nnow that the command has nine subcommands to describe.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: use Warning admonition instead of Caution[1]\n 🔗 1: https://lore.kernel.org/git/anLvVAyckm7S9Vo0@pks.im/\n\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex ce278c59bfc..3b5af936ed6 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -35,6 +35,21 @@ COMMANDS\n \n `migrate`::\n \tMigrate ref store between different formats.\n++\n+[WARNING]\n+--\n+The ref format migration has several known limitations in its current form:\n+\n+* It is not possible to migrate repositories that have worktrees.\n+\n+* There is no way to block concurrent writes to the repository during an\n+ ongoing migration. Concurrent writes can lead to an inconsistent migrated\n+ state. Users are expected to block writes on a higher level. If your\n+ repository is registered for scheduled maintenance, it is recommended to\n+ unregister it first with git-maintenance(1).\n+\n+These limitations may eventually be lifted.\n+--\n \n `verify`::\n \tVerify reference database consistency.\n@@ -130,21 +145,6 @@ The following options are specific to commands which write references:\n \tOperate on itself rather than the reference it points to via a\n \tsymbolic ref.\n \n-KNOWN LIMITATIONS\n------------------\n-\n-The ref format migration has several known limitations in its current form:\n-\n-* It is not possible to migrate repositories that have worktrees.\n-\n-* There is no way to block concurrent writes to the repository during an\n- ongoing migration. Concurrent writes can lead to an inconsistent migrated\n- state. Users are expected to block writes on a higher level. If your\n- repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n-\n-These limitations may eventually be lifted.\n-\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549768","messageId":"V2_linkgit_maintenance.b22@msgid.xyz","threadId":"66093","inReplyTo":"V2_CV_git_ref_migration_warning.b20@msgid.xyz","subject":"[PATCH v2 2/2] doc: refs: linkgit to git-maintenance(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-05T19:02:36Z","receivedAt":"2026-08-05T19:03:44Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAcked-by: Patrick Steinhardt \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: add Ack from previous round\n\n Documentation/git-refs.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 3b5af936ed6..9063892651e 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:\n ongoing migration. Concurrent writes can lead to an inconsistent migrated\n state. Users are expected to block writes on a higher level. If your\n repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n+ unregister it first with linkgit:git-maintenance[1].\n \n These limitations may eventually be lifted.\n --\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549785","messageId":"anQYWlv3UhpS3iE7@pks.im","threadId":"66093","inReplyTo":"V2_CV_git_ref_migration_warning.b20@msgid.xyz","subject":"Re: [PATCH v2 0/2] doc: refs: put ref migration warning under the command","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2026-08-06T05:15:06Z","receivedAt":"2026-08-06T05:15:15Z","isPatch":true,"body":"On Wed, Aug 05, 2026 at 09:02:34PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n> § Changes in v2\n> \n> • Patch 1/2: Use Warning admonition instead of Caution\n> • Patch 2/2: Add Ack\n\nThanks, I'm happy with this version!\n\nPatrick\n"},{"id":"549791","messageId":"V3_CV_git_ref_migration_warning.b23@msgid.xyz","threadId":"66093","inReplyTo":"CV_git_ref_migration_warning.b09@msgid.xyz","subject":"[PATCH v3 0/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-06T06:20:20Z","receivedAt":"2026-08-06T06:20:50Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nTopic name (applied): doc-refs-migrate-limitations\n\nTopic summary: Put ref migration warning as an admonition under the command\nso that it is visible.\n\nThat’s the first patch. The second patch adds a missing `linkgit` since it\ntouches that same warning text.\n\nI have two other patches that are not included here. They are unrelated\ncleanups that I will post later. Here are the commit subjects and the first\nparagraph so that you can see what they are about:\n\n• doc: refs: wrap standalone placeholders in underscores\n\n This is a synopsis manpage which means that standalone placeholders[1]\n are supposed to use underscores (_), not backticks (`).[2]\n• doc: refs: use inline-verbatim throughout\n\n Use inline-verbatim backticks (`) for literal commands, options, and\n subcommands listed under the “Commands” section.\n\n§ Cc list\n\nThe two people that I have the impression that have worked most on\nthis command.\n\n§ Changes in v3\n\n• Patch 1/2: Add Ack\n\n§ Link to v2\n\nhttps://lore.kernel.org/git/V2_CV_git_ref_migration_warning.b20@msgid.xyz/\n\n[1/2] doc: refs: put ref migration warning under the command\n[2/2] doc: refs: linkgit to git-maintenance(1)\n\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\nInterdiff against v2:\nRange-diff against v2:\n1: 8a6415e2d9b ! 1: 3ea1680afc8 doc: refs: put ref migration warning under the command\n @@ Commit message\n description. A one-page man page. But that is not the case anymore\n now that the command has nine subcommands to describe.\n \n + Acked-by: Patrick Steinhardt \n Signed-off-by: Kristoffer Haugsbakk \n \n ## Documentation/git-refs.adoc ##\n2: 801a3d7f539 = 2: 1d91be5762b doc: refs: linkgit to git-maintenance(1)\n\nbase-commit: 13c7afec212fc97ce257d15601659314c6673d6c\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549792","messageId":"V3_ref_migration_warning.b24@msgid.xyz","threadId":"66093","inReplyTo":"V3_CV_git_ref_migration_warning.b23@msgid.xyz","subject":"[PATCH v3 1/2] doc: refs: put ref migration warning under the command","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-06T06:20:21Z","receivedAt":"2026-08-06T06:21:08Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nI have to scroll down at least three screens in man(1) from the\n`migrate` description in order to see the “known limitations” for\nit. This is important information since the text says that concurrent\nwrites can lead to an inconsistent migrated state. Let’s move that text\nup to the command description and put it inside a Warning admonition.\n\nThis section made sense when it was added in 25a0023f (builtin/refs:\nnew command to migrate ref storage formats, 2024-06-06); `migrate` was\nthe only subcommand, and this section was visible from the command\ndescription. A one-page man page. But that is not the case anymore\nnow that the command has nine subcommands to describe.\n\nAcked-by: Patrick Steinhardt \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v3: add Ack from previous round\n v2: use Warning admonition instead of Caution[1]\n 🔗 1: https://lore.kernel.org/git/anLvVAyckm7S9Vo0@pks.im/\n\n Documentation/git-refs.adoc | 30 +++++++++++++++---------------\n 1 file changed, 15 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex ce278c59bfc..3b5af936ed6 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -35,6 +35,21 @@ COMMANDS\n \n `migrate`::\n \tMigrate ref store between different formats.\n++\n+[WARNING]\n+--\n+The ref format migration has several known limitations in its current form:\n+\n+* It is not possible to migrate repositories that have worktrees.\n+\n+* There is no way to block concurrent writes to the repository during an\n+ ongoing migration. Concurrent writes can lead to an inconsistent migrated\n+ state. Users are expected to block writes on a higher level. If your\n+ repository is registered for scheduled maintenance, it is recommended to\n+ unregister it first with git-maintenance(1).\n+\n+These limitations may eventually be lifted.\n+--\n \n `verify`::\n \tVerify reference database consistency.\n@@ -130,21 +145,6 @@ The following options are specific to commands which write references:\n \tOperate on itself rather than the reference it points to via a\n \tsymbolic ref.\n \n-KNOWN LIMITATIONS\n------------------\n-\n-The ref format migration has several known limitations in its current form:\n-\n-* It is not possible to migrate repositories that have worktrees.\n-\n-* There is no way to block concurrent writes to the repository during an\n- ongoing migration. Concurrent writes can lead to an inconsistent migrated\n- state. Users are expected to block writes on a higher level. If your\n- repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n-\n-These limitations may eventually be lifted.\n-\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549793","messageId":"V3_linkgit_maintenance.b25@msgid.xyz","threadId":"66093","inReplyTo":"V3_CV_git_ref_migration_warning.b23@msgid.xyz","subject":"[PATCH v3 2/2] doc: refs: linkgit to git-maintenance(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-08-06T06:20:22Z","receivedAt":"2026-08-06T06:21:26Z","isPatch":true,"body":"From: Kristoffer Haugsbakk \n\nAcked-by: Patrick Steinhardt \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2: add Ack from previous round\n\n Documentation/git-refs.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc\nindex 3b5af936ed6..9063892651e 100644\n--- a/Documentation/git-refs.adoc\n+++ b/Documentation/git-refs.adoc\n@@ -46,7 +46,7 @@ The ref format migration has several known limitations in its current form:\n ongoing migration. Concurrent writes can lead to an inconsistent migrated\n state. Users are expected to block writes on a higher level. If your\n repository is registered for scheduled maintenance, it is recommended to\n- unregister it first with git-maintenance(1).\n+ unregister it first with linkgit:git-maintenance[1].\n \n These limitations may eventually be lifted.\n --\n-- \n2.54.0.22.g9e26862b904\n\n"},{"id":"549836","messageId":"CAOLa=ZQQnrRca60BAfnm6Azu=bHvnoVhcGwQ3KkDT7yqLDd8Dw@mail.gmail.com","threadId":"66093","inReplyTo":"V3_CV_git_ref_migration_warning.b23@msgid.xyz","subject":"Re: [PATCH v3 0/2] doc: refs: put ref migration warning under the command","fromName":"Karthik Nayak","fromEmail":"karthik.188@gmail.com","sentAt":"2026-08-06T11:01:12Z","receivedAt":"2026-08-06T11:01:13Z","isPatch":true,"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Topic name (applied): doc-refs-migrate-limitations\n>\n> Topic summary: Put ref migration warning as an admonition under the command\n> so that it is visible.\n>\n> That’s the first patch. The second patch adds a missing `linkgit` since it\n> touches that same warning text.\n>\n> I have two other patches that are not included here. They are unrelated\n> cleanups that I will post later. Here are the commit subjects and the first\n> paragraph so that you can see what they are about:\n>\n> • doc: refs: wrap standalone placeholders in underscores\n>\n> This is a synopsis manpage which means that standalone placeholders[1]\n> are supposed to use underscores (_), not backticks (`).[2]\n> • doc: refs: use inline-verbatim throughout\n>\n> Use inline-verbatim backticks (`) for literal commands, options, and\n> subcommands listed under the “Commands” section.\n>\n> § Cc list\n>\n> The two people that I have the impression that have worked most on\n> this command.\n>\n\nSorry for the late review, been a bit busy. The two patches look good to\nme! Thanks!\n"},{"id":"549873","messageId":"xmqqpkzvjgt8.fsf@gitster.g","threadId":"66093","inReplyTo":"anQYWlv3UhpS3iE7@pks.im","subject":"Re: [PATCH v2 0/2] doc: refs: put ref migration warning under the command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-08-06T17:32:19Z","receivedAt":"2026-08-06T17:32:21Z","isPatch":true,"body":"Patrick Steinhardt writes:\n\n> On Wed, Aug 05, 2026 at 09:02:34PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n>> § Changes in v2\n>> \n>> • Patch 1/2: Use Warning admonition instead of Caution\n>> • Patch 2/2: Add Ack\n>\n> Thanks, I'm happy with this version!\n>\n> Patrick\n\nThanks, both. Let me mark the topic for 'next', then.\n"}]}