Git: How to alias “master” as “main”
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 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.
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
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
origin/main an alias for
$ git symbolic-ref refs/remotes/origin/main refs/remotes/origin/master
You can then switch to the aliased
$ git switch main Switched to branch 'main'
main anywhere you’d previously need
$ git rebase -i main ... $ git log origin/main..example ... $ # etc.
Git will show both
master in some views, like
$ 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
[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
! 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 From github.com:adamchainz/example * [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 From github.com:adamchainz/example - [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.
Make your development more pleasant with Boost Your Django DX.
One summary email a week, no spam, I pinky promise.