Subject: Re: [PATCH] refs: support migration with worktrees

From: Junio C Hamano <[email-masked]>
Date: Tue, 28 Oct 2025 09:00:43 -0700

Patrick Steinhardt <[email-masked]> writes:

>>  `migrate`::
>> -	Migrate ref store between different formats.
>> +	Migrate ref store between different formats. Supports repositories
>> +	with worktrees; migration must be run from the main worktree.
>
> It feels a bit weird to single our worktrees specifically. We don't say
> that the tool supports bare and non-bare repositories, either, so the
> only reason why we'd have the note about worktrees is historic legacy.
> How about this instead:
>
>     Migrate ref storage between different formats. Must be run from the
>     main worktree in case the repository uses worktrees.

Two thoughts.

 * Would it be unacceptable if the primary repository and refstore
   uses reftable backend, and a newly attached worktree to the
   repository uses ref-files only for its per-worktree refs?  If we
   should allow it, then "if the ref store you are migrating is in a
   repository with multiple worktrees, you must migrate from the
   primary and migrate _all_ ref store for all worktrees at once,
   into the same backend", which the design of this patch seems to
   aim at, would contradict with it, no?

 * If "you must do so from the primary worktree and we convert all
   the worktrees attached to the same repository" is the only mode
   of operation we support (which by the way I have no problem
   with---the first bullet point above was asking question, not
   suggesting change of design), then would it be easier for the
   user to use if the command noticed that it is not in the primary
   worktree and switched to it for the user, instead of complaining
   and failing?

>> @@ -95,7 +96,7 @@ KNOWN LIMITATIONS
>>  
>>  The ref format migration has several known limitations in its current form:
>>  
>> -* It is not possible to migrate repositories that have worktrees.
>> +* Migration must be run from the main worktree.
>>  
>
> I'd drop this bullet point entirely, as I don't really see this as a
> limitation anymore.

I agree that such a limitation should be lifted, but if we have to
say "you must do it this way, not that way", that is still a
limitation ;-).