How to Rename the master branch to main in Git

For the longest time, the default branch in most Git repositories was named "master". Fortunately, many people have become aware that this terminology (even more evident in "master/slave") should be replaced! The tech industry should move to a more inclusive, open culture - and removing language like "master/slave" is an important step in this journey.

In the public discussion, a handful of different alternatives for "master" have popped up, "default" and "primary" being some of them. But the most popular term seems to be "main".

This short article will help you rename "master" in your own Git repositories to "main" (or any other term your team has chosen).

Renaming the Local master Branch to main

The first step is to rename the "master" branch in your local Git repositories:

$ git branch -m master main

Let's quickly check if this has worked as expected:

$ git status
On branch main
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

So far, so good! The local branch has been renamed - but we now need to make some changes on the remote repository as well!

Renaming the Remote master Branch as Well

In the second step, we'll have to create a new branch on the remote named "main" - because Git does not allow to simply "rename" a remote branch. Instead, we'll have to create a new "main" branch and then delete the old "master" branch.

Make sure your current local HEAD branch is still "main" when executing the following command:

$ git push -u origin main

We now have a new branch on the remote named "main". Let's go on and remove the old "master" branch on the remote:

$ git push origin --delete master

Depending on your exact setup, this might have worked and the renaming is successful. In many cases, however, you will see an error message like the following one:

To https://github.com/gittower/git-crashcourse.git
! [remote rejected]   master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'https://example@github.com/gittower/git-crashcourse.git'

GitHub, like other code-hosting platforms, too, expects you to define a "default" branch - and deleting this is not allowed. Additionally, your old "master" might be set as "protected". You'll need to resolve this before you can go on. Here's how to do this in GitHub:

If you try again now, deleting "master" from the remote repository should be successful:

$ git push origin --delete master
To https://github.com/gittower/git-crashcourse.git
 - [deleted]           master

What Your Teammates Have to Do

If other people on your team have local clones of the repository, they will also have to perform some steps on their end:

# Switch to the "master" branch:
$ git checkout master

# Rename it to "main":
$ git branch -m master main

# Get the latest commits (and branches!) from the remote:
$ git fetch

# Remove the existing tracking connection with "origin/master":
$ git branch --unset-upstream

# Create a new tracking connection with the new "origin/main" branch:
$ git branch -u origin/main

In case you're using the Tower Git client, your colleagues can simply rename their local "master" branch and then change the tracking connection in the contextual menu:

Things to Keep in Mind

As you've seen, the process of renaming "master" to "main" isn't terribly complicated.

One thing to keep in mind, though, is your toolchain: if you're using a CI/CD tool, GitHub Actions, Azure DevOps / Atlassian Bamboo / GitLab CI pipelines or anything like this, you should check these tools thoroughly. If they depend on a specific "origin/master" branch, you might have to change their settings, too.

Learn More

• More frequently asked questions about Git & version control