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

> 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"?