Re: [PATCH 9/9] builtin/refs: new command to migrate ref storage formats

[Eric Sunshine <sunshine@sunshineco.com>]

On Thu, May 23, 2024 at 4:26 AM Patrick Steinhardt <ps@pks.im> wrote:
> Introduce a new command that allows the user to migrate a repository
> between ref storage formats. This new command is implemented as part of
> a new git-refs(1) executable. This is due to two reasons:
>
>   - There is no good place to put the migration logic in existing
>     commands. git-maintenance(1) felt unwieldy, and git-pack-refs(1) is
>     not the correct place to put it, either.
>
>   - I had it in my mind to create a new low-level command for accessing
>     refs for quite a while already. git-refs(1) is that command and can
>     over time grow more functionality relating to refs. This should help
>     discoverability by consolidating low-level access to refs into a
>     single executable.
>
> As mentioned in the preceding commit that introduces the ref storage
> format migration logic, the new `git refs migrate` command still has a
> bunch of restrictions. These restrictions are documented accordingly.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> diff --git a/Documentation/git-refs.txt b/Documentation/git-refs.txt
> @@ -0,0 +1,59 @@
> +--dry-run::
> +       Perform the migration, but do not modify the repository. The migrated
> +       refs will be written into a separate directory that can be inspected
> +       separately. This can be used to double check that the migration works
> +       as expected before doing performing the actual migration.

s/doing performing/performing/

The mysterious "into a separate directory" is never made concrete. Can
this provide more information so the reader can know where this
directory is and how to double-check that it worked "as expected"?