Skip to main content
Let’s get started!
View all Services
Development
Design
Product
Team and Processes
View all Services
View all Resources
Development
The business of great software
View all Resources

It's time for a new branch

Joe Ferris

Terminology with racist origins is endemic in our society, and technology is not exempt. From a position of privilege, I have casually used terms like “master” and “slave” without acknowledging the pain they cause others. In recent years, technologies have started to abandon these terms in favor of less harmful language, from databases like Postgres and Redis to languages like Python. One of my favorite tools has been slow to let go, however: Git.

It’s hard to overstate how central Git is to our workflow as developers. The Git history is the single source of truth for a project. It is the fountain of blame and praise. We use it to refactor, deploy, review, debug, and roll back. It forms the basis of most of our tools for communication and collaboration, and it underpins much of the modern open source movement.

Given how central this tool is, many have pushed back on changing the default branch name. It will require changes to our workflows, configurations, and integrations. But given how central this tool is, it makes it an especially important place to move forward.

One of the most compelling aspects of Git coming from Subversion was how easy it was to make branches. Branches are cheap, fast, and disposable. You can experiment, rebase, and merge. Let’s use one of Git’s greatest strengths to overthrow the racist origins of its terminology. Let’s start a new branch.

We are in the process of moving our workflows and repositories to use main as the default branch instead of master.

Init

If you start a lot of new projects, one of the best ways to start shifting towards main is to change how Git initializes new repositories.

As of Git 2.28, you can set init.defaultBranch so that new Git directories will initialize with a main branch rather than master:

git config --global init.defaultBranch main

Default Branches In GitHub

If you create an empty repository in GitHub and push to it, the first branch you push will become the default branch. If you start out with a main branch, you’ll get main.

For existing repositories, you can make the switch fairly quickly. You can rename your local master branch to main and push it:

git branch -m master main
git push -u origin main

You can then change the default branch settings for your repository in GitHub to main and delete the master branch:

git push origin :master

Deleting the master branch is even more fun than force pushing to it!

But wait! There’s more!

GitHub now allows you to set the default branch for new repositories. If you prefer to have GitHub initialize your repositories rather than pushing to a blank slate, this setting is for you. It can be configured per-user or per-organization. The default is also changing to main in October. Thanks, GitHub!

Fast Forward

We’re still learning what just works and what just doesn’t, but here are some tips from our experiences so far:

  • GitHub Actions use the default branch rather than an explicit master branch, so they seem to work without changes.
  • Heroku’s Git deploys still require you to push to the master branch, but you can deploy your main branch by running git push heroku main:master.
  • Heroku’s GitHub-based deploys let you configure a branch to auto-deploy.
  • RubyDoc.info will pick up a different default branch if you add a project from GitHub.
  • If you’re referencing master in aliases or commands, you can use git symbolic-ref --short refs/remotes/origin/HEAD to get the primary branch if it’s set on a Git repository.

Unmerged

We still have a lot of repositories to move over. As integrations and tooling improve, we expect this to move faster.

For open source and documentation projects, we’re moving a little slower to avoid breaking existing pull requests and other references. GitHub will currently redirect links to deleted branches to your default branch, but open pull requests are still affected. GitHub is working on [enhanced renaming functionality] that is slated to be released by the end of the year. Their current recommendation is to wait until the release of this functionality, which will make it possible to rename the default branch without breaking anything.

Checking Out

If you’re still painting the bike shed about your new primary branch name, try to remember that branch names aren’t forever. You can always change it again. Try changing one repository today to use main instead of master.