Git: How to alias “master” as “main”

Don’t tangle up those branches!

The Git community is gradually moving the default branch name from “master” to “main”, because the term “master” is hurtful to some people as it refers to slavery.

Git 2.28 (2020-07-27) introduced the init.defaultBranch option, which controlls the default branch name for repos created with git init:

$ git config --global init.defaultBranch main

Git will move the default value for this setting from “master” to “main” in due course. Major Git hosting services already use “main” as the default for repos created through their interfaces: BitBucket, GitHub, and GitLab.

Pro Aliasing

It can be annoying to work on legacy repos that still have a “master” branch. Your muscle memory or command aliases might use “main”, causing your commands to fail:

$ git switch main
fatal: invalid reference: main

Sad times.

Luckily, Git offers a solution: local aliases, called “symbolic refs”, which you can configure with git symbolic-ref. You can make main an alias for master like so:

$ git symbolic-ref refs/heads/main refs/heads/master

And origin/main an alias for origin/master with:

$ git symbolic-ref refs/remotes/origin/main refs/remotes/origin/master

You can then switch to the aliased main branch:

$ git switch main
Switched to branch 'main'

…nd use main anywhere you’d previously need master:

$ git rebase -i main
$ git log origin/main..example
$ # etc.

Nice one!

Git will show both main and master in some views, like git log:

$ git log --oneline
0e78b70 (HEAD -> master, main) Make the damn thing
275a9fd (origin/master, origin/main) Initial commit

Good to know.

An alias to alias

You could reopen this blog post to copy and paste the above git symbolic-ref commands every time you need them. Or, you could add a Git command alias to make it easy for yourself.

You can add such a command alias with this one-liner:

$ git config --global alias.alias-master-as-main '!git symbolic-ref refs/heads/main refs/heads/master && git symbolic-ref refs/remotes/origin/main refs/remotes/origin/master && git switch main'

This will add an entry in your ~/.gitconfig:

    alias-master-as-main = !git symbolic-ref refs/heads/main refs/heads/master && git symbolic-ref refs/remotes/origin/main refs/remotes/origin/master && git switch main

The ! tells Git to run the alias with a shell, allowing it to use multiple commands. The && is Posix shell syntax for running several commands in a row, stopping on failure.

Now, when you need to add a main alias to a new legacy repo, you can run:

$ git alias-master-as-main
Switched to branch 'main'

Seconds saved every time.

If the remote updates

If/when the remote repository changes from “master” to “main”, you’ll need to update locally.

(How to’s: BitBucket, GitHub, GitLab.)

First, remove your symbolic refs, with -d for delete:

$ git switch master
$ git symbolic-ref -d refs/heads/main
$ git symbolic-ref -d refs/remotes/origin/main

Second, update to use the remote repository:

$ git branch -m master main
$ git fetch origin
 * [new branch]      main       -> origin/main
$ git branch -u origin/main main
branch 'main' set up to track 'origin/main'.
$ git remote set-head origin -a
origin/HEAD set to main
$ git fetch --prune
 - [deleted]         (none)     -> origin/master

These are the same commands that GitHub’s interface shows after renaming the default branch, plus the git fetch --prune to tidy up.

If you find yourself doing this a lot, maybe another command alias could help save you some time.


Keep it mainstream,


Make your development more pleasant with Boost Your Django DX.

Subscribe via RSS, Twitter, Mastodon, or email:

One summary email a week, no spam, I pinky promise.

Related posts: