Subject: Feature request: Provide porcelain to manage symbolic references as branch aliases

From: Phil Sainty <[email-masked]>
Date: Wed, 30 Apr 2014 00:51:47 +1200

Most of the plumbing for having branch name aliases already exists
in the form of symbolic references, and people do use them for this
purpose; but I get the impression that it's not really supported
officially, and I'm not aware of any porcelain features to
facilitate this use-case.

I'd like to propose that such porcelain be added. I feel that a new
argument to 'git branch' would make the most sense:

git branch --alias <alias> [<branch>]

For reference/testing, I'm attaching a wrapper script I wrote to
implement the same functionality (as a separate command). I did this
primarily to provide the error-checking I felt was needed to make it
practical to use branch aliases -- git symbolic-ref will happily
trash your branch references if you make a mistake, whereas it's
pretty difficult to mess anything up with my git-branch-alias script.

Thus far it's worked nicely for me. Examples:

$ git branch-alias short some-overly-long-branch-name # creates alias
$ git branch-alias short # creates alias for current branch
$ git log short
$ git checkout short
$ git push origin short # pushes the branch, not the alias/reference
$ git branch-alias --delete short

n.b. For my proposed porcelain change, these examples would become:
$ git branch --alias short some-overly-long-branch-name # creates alias
$ git branch --alias short # creates alias for current branch
$ git branch --delete short # works since 1.8.0.1, but see below.

Since using this script, the only thing I've spotted that I'd like
to be different is the commit message if I "git merge <alias>". The
commit message indicates that I've merged <alias> rather than the
<branch> that it points at. I'd prefer that it was dereferenced
when the message was generated, so that the real branch name was
printed instead.

That niggle aside, significant things I noted along the way were:

1. Git 1.8.0.1 fixed the problem whereby git branch -d <symref>
   used to dereference <symref> and therefore delete the branch
   it pointed at, rather than the reference.

2. HOWEVER if you have <symref> checked out at the time you
   delete it, you're in trouble -- git allows you to do it, and
   you're then left with an invalid HEAD reference.

   (I think this ought to be considered a current bug in git.)

3. I resolved that situation (2) by using "git symbolic-ref HEAD"
   to find the target ref, and setting HEAD to that target. Nothing
   changes for the user, but we can now delete the reference safely.

   HOWEVER, there's a problem with detecting that situation (2)
   in the first place:

4. Chains of references are de-referenced atomically -- the entire
   reference chain is followed to its end; and I could find no
   facility to obtain ONLY the "next link of the chain".

   This means we can't use "git symbolic-ref HEAD" to check whether
   it points to another reference. In my script I had to resort to
   inspecting HEAD manually, which obviously isn't desirable.

   I think a new argument is warranted here, perhaps something like:
   "git symbolic-ref --max-deref-count=1"

   I'll justify that on the assumption that (2) needs fixing in git
   regardless, either by:

   (i) Not allowing the user to delete the checked-out symref (which
       would be consistent with the behaviour if the user attempts to
       "git branch -d <branch>" (for an actual branch name) when that
       is the currently checked-out branch.

   or,
   (ii) Using the approach I've taken: silently setting HEAD to the
        branch to which the symref points before deleting that symref.
        (I couldn't see any reason not to use this approach.)

   But as in both cases we need to detect that HEAD is the symref
   being deleted, which means that we need the ability to explicitly
   dereference only a single step of a reference chain.

-Phil