Renaming the Default Branch in GitHub

Jun 17, 2020

This is a quick guide to changing the "master" branch in GitHub to something less racially charged.

A lot of people might be surprised to learn that "master" has no special meaning to Git and is only a convention. This is good, because conventions are relatively easy to change.

The biggest burden at the time of this publication are the small number of tools that hard-code "master" as the default instead of reading the "default_branch" key from the GitHub API. I have been pleasantly surprised at the number of tools that already do the right thing. The few that do not work are likely to get fixed soon enough. If more people switch the name of their default branch, these fixes will come even more quickly.

What should I call the main place code branches off of? A lot of people have suggested this be called "main," but I think the more obvious name is "trunk." Since Git likes to mimic trees in other places, we might as well take the name from the tree (see figure 1). This guide will work just fine with other names, just replace "trunk" with whatever you choose.

**Figure 1**: A diagram correctly labeling the "trunk" of the tree. You can tell that I am right-handed.

First, you need to rename the branch locally and upload it to GitHub with that new name.

git branch --move master trunk
git push origin --set-upstream trunk

Next, go to the repository on GitHub and open Settings > Branches. You will find a heading titled Default Branch.

Select the "trunk" you uploaded and click Update. Some prompt will appear warning you of the consequences of your actions. We will fix these things.

Any outstanding pull requests are likely to be against the "master" branch. If you delete "master" at this point, GitHub will close all PRs targeting it. If you want to keep those PRs open, the owners of the PRs must update the target branch to "trunk" (there does not appear to be a way to do this as a repository owner).

At this point, you should update any integrations to point to the new "trunk" branch. Most CI tools work with whatever name you gave them when you set it up in the first place and will not react to a change to the default. Your job here is to find the strings pointing to "master" and change them to "trunk" instead.

The final step is to delete "master" from GitHub.