Re: Renaming the "master" branch without breaking existing clones

From: Taylor Blau <me@ttaylorr.com>
Date: Aug 3, 2020, 16:00 UTC
Message-ID: <20200803160051.GA50799@syl.lan>
In-Reply-To: <ec960483f5008e9948271c678d51876920ab62c9.camel@mattmccutchen.net>

On Mon, Aug 03, 2020 at 08:15:58AM -0400, Matt McCutchen wrote:

> [Apologies if there is an existing thread about this; I searched hard
> and wasn't able to find one.]

Perhaps this isn't exactly what you're going for, but I raised a similar point a couple of months ago:

  https://lore.kernel.org/git/20200611010720.GA21728@syl.local/

Show 8 quoted lines

> I've just become aware of the discussion that the name of the "master"
> branch should be changed.  I'm not taking a position on this now, but
> it seems enough people want to make the change that we should resolve
> the technical problems, of which I see several:
>
> 1. Allowing tools to be configured to change the default name for new
> repositories.  Work on this appears to be well underway with no
> fundamental obstacles.

Yes, this was released with 2.28. Users can set 'init.defaultBranch' and have 'git init' respect it when creating the first branch in a new repository.

Show 26 quoted lines

> 2. Renaming the branch in existing repositories.  I've seen a number of
> guides for how to do it in the central repository, and they all seem to
> expect users with existing clones to manually reconfigure them all at
> once.  To me, that amount of disruption would be unacceptable for
> central repositories I'm in charge of (admittedly few with few users,
> so I imagine some will argue I should leave it to the bigger players to
> complain about this), whether or not one believes that the social
> justice benefit of changing the branch name in personal clones merits
> the work at all.  I found only one guide that addresses this problem:
>
> https://github.com/chancancode/branch-rename#gradual-migration
>
> It includes a procedure to mirror the "master" branch from the new
> default branch so that readers of the central repository don't need to
> reconfigure anything.  Writers need to be reconfigured.  That seems
> reasonable to me.
>
> Unfortunately, the mirroring method seems to be specific to the
> repository hosting service being used.  If services supported standard
> git hooks, that would probably work, but I can understand if the
> services don't because it's unwieldy to execute shell scripts without
> introducing security risks.
>
> This guide seems well thought out to me on a first read, but I suspect
> there may be aspects that could benefit from a lot more scrutiny from
> experts, and I want to encourage them to provide it.

This is more-or-less what I was proposing in the message that I linked above. Maybe a more solidified proposal might look something as follows:

  - We could introduce a mechanism to mark certain refs as aliases to
    other refs. For example, a remote might publish its
    'refs/heads/master' as an alias to 'refs/heads/main', so that any
    reads or writes to the former get applied to the latter
    transparently.

  - A ref alias can be annotated to say "I am a transition ref alias",
    i.e., that clients should be taught to rename their copy of 'master'
    to 'main' (and update remote-tracking refs accordingly).

  - Clients can enable/disable automatic branch renaming.

I am a little uncomfortable with the idea that a 'git pull' would modify 'refs/{heads,tags}' in addition to 'refs/remotes'. We expect that 'git pull' will touch remote refs, and we sometimes expect it to update non-remote refs when they are remote-tracking.

So, I think that you'd only want to let ref aliases automatically rename remote tracking references, and only if the user opted in to automatic renaming.

I'm not sure, though. I haven't thought about it too much.

Show 16 quoted lines

> 3. Ensuring that tools detect the default branch of a given repository
> in an appropriate way rather than assuming "master".  Where applicable,
> the remote HEAD symref is probably the best thing to use.  See for
> example:
>
> https://github.com/chancancode/branch-rename#packages-considerations
>
> This category would also include git's feature of leaving the target
> branch name out of the merge message, for example.  I believe the
> necessary work on git itself is underway; other tools may lag.
>
> For read-only tools, this mainly matters for central repositories that
> eventually delete their "master" branch, which may not be all of them,
> but again, it sounds like there will be enough such repositories that
> we should consider the problem.  I don't see any fundamental obstacle,
> but this may benefit from more scrutiny as well.

I'm less qualified to talk about what's going on here, but my understanding is that providers and tool-makers are quite aware of this.

Show 5 quoted lines

> I'm aware that asking others to do work is often poorly received.  This
> message is just to get people's attention so they can do the work if
> they wish.
>
> Thanks for reading.

Thanks for your concern.

> Matt

Thanks, Taylor