---
title: It's time for a new branch
teaser: 'It''s easy to check out new branches in Git. We''re moving forward with main
  and leaving master for the reflog.

  '
tags: news,git
author: Joe Ferris
published_on: 2020-08-31
---

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!

[change the default branch settings for your repository in GitHub]: https://help.github.com/en/github/administering-a-repository/setting-the-default-branch

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!

[set the default branch for new repositories]: https://github.blog/changelog/2020-08-26-set-the-default-branch-for-newly-created-repositories/

## 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.

[redirect links to deleted branches]: https://github.com/github/renaming/#now-supporting-early-movers-

## 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`.