@matheusbsbs / matheus-bagliano / commits / 65edea454e

doc: refs: put ref migration warning under the command

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Kristoffer Haugsbakk committed Jul 31, 2026 at 11:07 UTC 65edea454e1e767ec962f279c251aa7c29359f5d
1 file changed +15 -15
Documentation/git-refs.adoc
+15 -15
@@ -35,6 +35,21 @@ COMMANDS
35
36 `migrate`::
37 Migrate ref store between different formats.
38 ++
39 +[CAUTION]
40 +--
41 +The ref format migration has several known limitations in its current form:
42 +
43 +* It is not possible to migrate repositories that have worktrees.
44 +
45 +* There is no way to block concurrent writes to the repository during an
46 + ongoing migration. Concurrent writes can lead to an inconsistent migrated
47 + state. Users are expected to block writes on a higher level. If your
48 + repository is registered for scheduled maintenance, it is recommended to
49 + unregister it first with git-maintenance(1).
50 +
51 +These limitations may eventually be lifted.
52 +--
53
54 `verify`::
55 Verify reference database consistency.
@@ -130,21 +145,6 @@ The following options are specific to commands which write references:
145 Operate on <ref> itself rather than the reference it points to via a
146 symbolic ref.
147
133 -KNOWN LIMITATIONS
134 ------------------
135 -
136 -The ref format migration has several known limitations in its current form:
137 -
138 -* It is not possible to migrate repositories that have worktrees.
139 -
140 -* There is no way to block concurrent writes to the repository during an
141 - ongoing migration. Concurrent writes can lead to an inconsistent migrated
142 - state. Users are expected to block writes on a higher level. If your
143 - repository is registered for scheduled maintenance, it is recommended to
144 - unregister it first with git-maintenance(1).
145 -
146 -These limitations may eventually be lifted.
147 -
148 GIT
149 ---
150 Part of the linkgit:git[1] suite