Subject: Re: [PATCH 0/9] refs: ref storage format migrations

From: Patrick Steinhardt <[email-masked]>
Date: Tue, 28 May 2024 07:13:46 +0200

On Fri, May 24, 2024 at 09:28:13AM -0700, Junio C Hamano wrote:
> Patrick Steinhardt <[email-masked]> writes:
> 
> >> Documenting the limitation is a good place to start.  For normal
> >> users, would it be sufficient to
> >> 
> >>  (1) tell your colleagues that this repository is currently closed
> >>      and do not push into it;
> >> 
> >>  (2) configure "git gc --auto" to never kick in;
> >> 
> >>  (3) delist the repository from "git maintenance" schedule.
> >> 
> >> before they try this feature out?
> >
> > I think (2) wouldn't even be needed. Auto-GC only kicks in when there is
> > a write in the repository, and if both (1) and (3) are true then there
> > are none. But other than that yes, (1) and (3) should be sufficient.
> 
> So it may make sense to document something like that at least?

It is documented as part of the new git-refs(1) man page, in the "Known
limitations" section:

    * There is no way to block concurrent writes to the repository during an
      ongoing migration. Concurrent writes can lead to an inconsistent migrated
      state. Users are expected to block writes on a higher level. If your
      repository is registered for scheduled maintenance, it is recommended to
      unregister it first with git-maintenance(1).

Is that sufficient, or do you think we need to expand on this?

Patrick