[PATCH v2 0/2] doc: refs: put ref migration warning under the command
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name (applied): doc-refs-migrate-limitations
Topic summary: Put ref migration warning as an admonition under the command so that it is visible.
That’s the first patch. The second patch adds a missing `linkgit` since it touches that same warning text.
I have two other patches that are not included here. They are unrelated cleanups that I will post later. Here are the commit subjects and the first paragraph so that you can see what they are about:
• doc: refs: wrap standalone placeholders in underscores
This is a synopsis manpage which means that standalone placeholders[1]
are supposed to use underscores (_), not backticks (`).[2]
• doc: refs: use inline-verbatim throughout
Use inline-verbatim backticks (`) for literal commands, options, and
subcommands listed under the “Commands” section.
§ Cc list
The two people that I have the impression that have worked most on this command.
§ Changes in v2
• Patch 1/2: Use Warning admonition instead of Caution • Patch 2/2: Add Ack
§ Link to v1
https://lore.kernel.org/git/CV_git_ref_migration_warning.b09@msgid.xyz/
[1/2] doc: refs: put ref migration warning under the command [2/2] doc: refs: linkgit to git-maintenance(1)
Documentation/git-refs.adoc | 30 +++++++++++++++---------------
1 file changed, 15 insertions(+), 15 deletions(-)
Interdiff against v1:
Show changes to Documentation/git-refs.adoc +1 −1
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 1ec26be0b4f..9063892651e 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -36,7 +36,7 @@ COMMANDS
`migrate`::
Migrate ref store between different formats.
+
-[CAUTION]
+[WARNING]
--
The ref format migration has several known limitations in its current form:
Range-diff against v1:
1: cc4d9ca5006 ! 1: 8a6415e2d9b doc: refs: put ref migration warning under the command
@@ Commit message
`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.
+ 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
@@ Documentation/git-refs.adoc: COMMANDS
`migrate`::
Migrate ref store between different formats.
++
-+[CAUTION]
++[WARNING]
+--
+The ref format migration has several known limitations in its current form:
+
2: 7265de45c9d ! 2: 801a3d7f539 doc: refs: linkgit to git-maintenance(1)
@@ Metadata
## Commit message ##
doc: refs: linkgit to git-maintenance(1)
+ Acked-by: Patrick Steinhardt <ps@pks.im>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Documentation/git-refs.adoc ##
base-commit: 13c7afec212fc97ce257d15601659314c6673d6c
--
2.54.0.22.g9e26862b904