dilim/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2026-08-08 17:11:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: refs: put ref migration warning under the command

Browse Source 
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>
This commit is contained in:
Kristoffer Haugsbakk
2026-07-31 11:07:02 +02:00
committed by Junio C Hamano
parent a97fcc37c2
commit 65edea454e
1 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Documentation/git-refs.adoc
View File

@@ -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 <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