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

From: Jeff King <peff@peff.net>
Date: Aug 3, 2020, 20:45 UTC
Message-ID: <20200803204503.GB2715275@coredump.intra.peff.net>
In-Reply-To: <20200803194006.GA2715275@coredump.intra.peff.net>

On Mon, Aug 03, 2020 at 03:40:06PM -0400, Jeff King wrote:

Show 12 quoted lines

> On Mon, Aug 03, 2020 at 12:00:51PM -0400, Taylor Blau wrote:
> 
> > 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.
> 
> I think symrefs do this already. Try this:

Looks like Junio already mentioned symrefs. I guess I should have read the whole thread. :)

As he noted, they don't work if you want to free up the original name. But I think in the master/main renaming case that most people wouldn't care that much about doing so.

Show 6 quoted lines

> >   - 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).
> 
> It's not specifically marked as a transition, but a client could act on
> the symref advertisement above.

Something like this script could be run on the clients:

  remote=origin
  git ls-remote --symref $remote |
  grep ^ref: |
  while read junk to from; do
    if test "$from" = HEAD; then
      old=$(git symbolic-ref refs/remotes/$remote/HEAD)
      echo "Upstream switched their HEAD:"
      echo "  old: $old"
      echo "  new: $to"
      echo "Update to match?"
      read r </dev/tty
      if test "$r" = yes; then
        git symbolic-ref refs/remotes/$remote/HEAD $to
      fi
    else
      # do we even have the old branch?
      git rev-parse --verify $from >/dev/null 2>&1 || continue
      echo "Upstream is redirecting a branch:"
      echo "     branch: $from"
      echo "  points to: $to"
      echo "And you have a local $from; should we rename it?"
      read r </dev/tty
      if test "$r" = yes; then
        git branch -m ${from#refs/heads/} ${to#refs/heads/}
      fi
    fi
  done

There are probably some rough edges that could be smoothed (only looking in refs/heads/ and using branch names instead of fully qualified refs, handling the case that $to already exists more gracefully, better prompting). But something like that might be useful for projects that are transitioning.

Note that it only works with protocol v2, though, because we don't report non-HEAD symrefs in v0.

-Peff