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
the default branch instead of
If you start a lot of new projects, one of the best ways to start shifting
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
git config --global init.defaultBranch main
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
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
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,
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
masterbranch, so they seem to work without changes.
- Heroku’s Git deploys still require you to push to the
masterbranch, but you can deploy your
mainbranch 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
masterin aliases or commands, you can use
git symbolic-ref --short refs/remotes/origin/HEADto get the primary branch if it’s set on a Git repository.
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.
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