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

[Junio C Hamano <gitster@pobox.com>]

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.