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

Re: [PATCH 1/2] doc: refs: put ref migration warning under the command

From
Patrick Steinhardt <ps@pks.im>
Date
Aug 4, 2026, 14:30 UTC
Message-ID
<anH3k9PvWHMpWLT_@pks.im>
In-Reply-To
<ref_migration_warning.b0a@msgid.xyz>
On Fri, Jul 31, 2026 at 11:07:02AM +0200, kristofferhaugsbakk@fastmail.com wrote:
Show 13 quoted lines
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> 
> 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.
That feels quite sensible indeed.
Show 16 quoted lines
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  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 ce278c59bfc..98828041c23 100644
> --- a/Documentation/git-refs.adoc
> +++ b/Documentation/git-refs.adoc
> @@ -35,6 +35,21 @@ COMMANDS
>  
>  `migrate`::
>  	Migrate ref store between different formats.
> ++
> +[CAUTION]
> +--

Hm, okay, first time I see this format. It feels like the rendered version is indented once level too deep, but I guess that's more of a problem with how asciidoc decides to process this. And it's a tiny nit only that may not even be worth addressing.

Patrick
Previous: kristofferhaugsbakk@fastmail.comNext: Kristoffer Haugsbakk
Message 3 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.