git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date
Aug 5, 2026, 19:02 UTC
Message-ID
<V2_ref_migration_warning.b21@msgid.xyz>
In-Reply-To
<V2_CV_git_ref_migration_warning.b20@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

I have to scroll down at least three screens in man(1) from the `migrate` description in order to see the “known limitations” for it. This is important information since the text says that concurrent writes can lead to an inconsistent migrated state. Let’s move that text up to the command description and put it inside a Warning admonition.

This section made sense when it was added in 25a0023f (builtin/refs: new command to migrate ref storage formats, 2024-06-06); `migrate` was the only subcommand, and this section was visible from the command description. A one-page man page. But that is not the case anymore now that the command has nine subcommands to describe.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
    v2: use Warning admonition instead of Caution[1]
        🔗 1: https://lore.kernel.org/git/anLvVAyckm7S9Vo0@pks.im/
 Documentation/git-refs.adoc | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index ce278c59bfc..3b5af936ed6 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -35,6 +35,21 @@ COMMANDS
 
 `migrate`::
 	Migrate ref store between different formats.
++
+[WARNING]
+--
+The ref format migration has several known limitations in its current form:
+
+* It is not possible to migrate repositories that have worktrees.
+
+* There is no way to block concurrent writes to the repository during an
+  ongoing migration. Concurrent writes can lead to an inconsistent migrated
+  state. Users are expected to block writes on a higher level. If your
+  repository is registered for scheduled maintenance, it is recommended to
+  unregister it first with git-maintenance(1).
+
+These limitations may eventually be lifted.
+--
 
 `verify`::
 	Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
 	Operate on <ref> itself rather than the reference it points to via a
 	symbolic ref.
 
-KNOWN LIMITATIONS
------------------
-
-The ref format migration has several known limitations in its current form:
-
-* It is not possible to migrate repositories that have worktrees.
-
-* There is no way to block concurrent writes to the repository during an
-  ongoing migration. Concurrent writes can lead to an inconsistent migrated
-  state. Users are expected to block writes on a higher level. If your
-  repository is registered for scheduled maintenance, it is recommended to
-  unregister it first with git-maintenance(1).
-
-These limitations may eventually be lifted.
-
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
2.54.0.22.g9e26862b904
Previous: kristofferhaugsbakk@fastmail.comNext: kristofferhaugsbakk@fastmail.com
Message 12 of 19 in “doc: refs: put ref migration warning under the command”
  1. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Jul 31, 2026
  2. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Jul 31, 2026
  3. Patrick SteinhardtAug 4, 2026
  4. Kristoffer HaugsbakkAug 4, 2026
  5. Patrick SteinhardtAug 5, 2026
  6. Kristoffer HaugsbakkAug 5, 2026
  7. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Jul 31, 2026
  8. Patrick SteinhardtAug 4, 2026
  9. Junio C HamanoJul 31, 2026
  10. Patrick SteinhardtAug 4, 2026
  11. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 5, 2026
  12. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 5, 2026
  13. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Aug 5, 2026
  14. Patrick SteinhardtAug 6, 2026
  15. Junio C HamanoAug 6, 2026
  16. 0/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 6, 2026
  17. 1/2 doc: refs: put ref migration warning under the commandkristofferhaugsbakk@fastmail.com, Aug 6, 2026
  18. 2/2 doc: refs: linkgit to git-maintenance(1)kristofferhaugsbakk@fastmail.com, Aug 6, 2026
  19. Karthik NayakAug 6, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.