Rename Git’s Default Branch

If you’re interested in changing the default Git branch name from “master” to something else, here’s how you do it.

Make a new default branch

Start by duplicating master. I’m using “main” for this example but use whatever you like.

git switch --create main master

Then push it up and set the upstream.

git push -u origin main

Next change your default branch in GitHub to “main”.

And finally change the base branch of any open pull requests to “main”.

I initially thought it would be more complicated but this is basically it. All that’s left is to do a search for “master” in your repository and change any hardcoded references. External tools and services you use (like CI) might also need some tweaking.

There is one big gotcha, though. Some people are not going to rename their master branch, some people are going to go with whatever GitHub chooses, and some people are going to choose something else entirely.

If there is no universal default branch name, how do you make aliases and scripts that rely on one? You can’t hardcode “master” anymore, so what do you do?

Get the default branch name dynamically

Git doesn’t really have a concept of a local “default” branch, but it does have conveniences around dealing with remotes. For example, you can shorten git log origin/master to just git log origin and Git knows you mean to log the “master” branch.

The way Git does this is by keeping track (locally) of what branch origin/HEAD points to. That’s actually what’s happening when you change your default branch in GitHub—it updates origin/HEAD to point from origin/master to whatever your new default branch is.

All you need to do is tell your local repository to update its reference of what origin/HEAD points to.¹

git remote set-head origin --auto

Now you can use the git symbolic-ref command to get the default branch ref and filter out the branch name. You’ll want to make a Bash script so you can use reuse it.

Make a file named default_branch, put it somewhere in your path, and make it executable.

#!/usr/bin/env bash

git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

Now use this script anywhere you were previously hardcoding the name “master”.

For example, I have a Git alias for switching to my default branch.

[alias]
  swm = switch master

I need to tweak the alias syntax slightly so it can execute the script and dynamically get the default branch for the repository.

[alias]
  swd = "!git switch $(default_branch)"

Keep in mind that regardless of what shell you’re using, Git aliases are executed using Bash so you need to use Bash’s command substitution syntax.