Frequently asked questions around Git and Version Control.
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).
The Git Cheat Sheet
No need to remember all those commands and parameters: get our popular "Git Cheat Sheet" - for free!
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:
! [remote rejected] master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'https://firstname.lastname@example.org/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:
In case you are using the Tower Git client, you can rename branches very easily:
After creating the new "main" branch on the remote, you might then (depending on your Git hosting platform) have to change the "default" branch or remove any "protected" status for "master". You will then be able to delete the old "master" branch on the remote.
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.