From 4cc9039ff094a99aa2754c7b98ba6621079f0ca1 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 6 Aug 2026 08:20:21 +0200 Subject: [PATCH 1/2] doc: refs: put ref migration warning under the command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- 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 ce278c59bf..3b5af936ed 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 From 0dc68f404af778338a4090a857d51f16b9ed54b8 Mon Sep 17 00:00:00 2001 From: Kristoffer Haugsbakk Date: Thu, 6 Aug 2026 08:20:22 +0200 Subject: [PATCH 2/2] doc: refs: linkgit to git-maintenance(1) Acked-by: Patrick Steinhardt Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano --- 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 3b5af936ed..9063892651 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. --