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

[PATCH v2 0/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_CV_git_ref_migration_warning.b20@msgid.xyz>
In-Reply-To
<CV_git_ref_migration_warning.b09@msgid.xyz>
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:
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
Previous: Patrick SteinhardtNext: kristofferhaugsbakk@fastmail.com
Message 11 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.