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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 3, 2020, 16:14 UTC
Message-ID: <xmqqlfivwvtw.fsf@gitster.c.googlers.com>
In-Reply-To: <ec960483f5008e9948271c678d51876920ab62c9.camel@mattmccutchen.net>

Matt McCutchen <matt@mattmccutchen.net> writes:

> 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.

I wonder if that would work well. Your refs/remotes/origin/HEAD is designed to be tweaked by you to indicate which remote branch is of interest to you to your local Git. Those who are interested in following along 'maint' can update refs/remotes/origin/HEAD to point at refs/remotes/origin/maint in their clone of this project, and they can say "git fetch origin && git log origin" to see the history leading to the tip of 'maint' in my repository.

At least, that is how it is designed to work. So "compare local refs/remotes/origin/HEAD and what 'git ls-remote origin' sees where they point at with their HEAD---if they are different, ours have old name and theirs have new name" is not a good heuristics.

If we wanted to do this properly, I'd imagine we'd need to add a mechanism for repositories to convey "this branch that used to exist got renamed to this other name", not specifically for any "special" branch name (like 'master'). If we plan to never allow reusing the old and banned name, it probably is enough to turn the old name into a symbolic ref that points at the new name, e.g. in my repository

    $ git update-ref refs/heads/seen refs/heads/pu
    $ git update-ref -d refs/heads/pu
    $ git symbolic-ref refs/heads/pu refs/heads/seen

which would create a symbolic reference 'pu' that points at 'seen' to say "pu used to exist but it is now seen".

But that would not work well, as we must allow reusing the old name, as the primary point of renaming 'pu' to 'seen' in this project was so that we can accept topics from contributors whose anglicized name has 'p' and 'u' in capital letters as pu/$topicname branches. Having a symbolic ref 'pu' would defeat that plan.

So perhaps we'd need to emply the usual trick to have a blob on "meta" ref, say "refs/meta/ref-rename" might contain multiple tuples that tells the receiving end about each moved ref:

    - the name of the 'old' ref (e.g. 'refs/heads/pu')
    - the name of the 'new' ref (e.g. 'refs/heads/seen')
    - (optional) when the 'move' happened

As it does not make much sense to perform the local side migration silently and behind the user's back while the user is actively working in the repository, it is likely that the migration instruction would be written as a "perform this when it is convenient for you" one-time event. It may start by fetching the "meta/ref-rename" blob and perform "what to do when remote ref X is moved to remote ref Y" procedure.

That procedure should also be executable offline, without the remote end publishing the "meta/ref-rename" data. If you know your upstream has changed 'pu' to 'seen', you should be able to do

    $ git ref-migration-helper refs/remotes/origin/pu refs/remotes/origin/seen

so that many things related to these names are changed (and that is the most complex part---compared to that, conveying what rename the remote end did to the local Git is much simpler), including

    - renaming the remote-tracking branches (obvious)

    - reconfiguring local branches that have their upstream branch
      set to the 'old' remote-tracking branch to make their upstream
      branch to the 'new' remote-tracking branch.

There may be others.