How To Rename Your Git Repositories From "Master" to "Main"

Until recently, almost every Git repository had a default branch named "master". But thankfully, as part of a movement to make the tech industry more inclusive and open, many software teams and open source projects are moving away from this unhealthy naming.

There has been quite some debate about a good replacement. And while "default" and "primary" had been interesting candidates, most of the Git community seems to agree that "main" should be a good successor for the outdated "master".

Many Git hosting platforms like GitHub, GitLab, or Bitbucket will soon make changes on their end (or, depending on when exactly you read this post, they might already have done so). In the near future, if you create a new Git repository on any of these platforms, you will find "main" to be the new default branch.

But what about your current, existing projects? That's exactly what we'll be talking about in this post: how you can rename "master" to "main" in your existing Git repositories!

Step 1: Rename Your Local master Branch

The first step is to rename the local "master" branch in your local repositories. You can do that easily with the following command:

$ git branch -m master main

Let's make sure this has worked:

$ git branch
* main

Perfect! Our local branch has been renamed, but we now have to do the same on the remote side of things.

Step 2: Rename Your Remote master Branch

It's not possible to actually "rename" a remote branch in Git. Instead, we simply have to create a new "main" branch - and then delete the old "master" branch.

First, you should make sure that your current HEAD branch is the newly created "main". Then, you can simply push this branch and thereby create it on the remote:

$ git checkout main
$ git push -u origin main

We can now delete the obsolete "master" branch on the remote with the following command:

$ git push origin --delete master

It might very well be that this has already worked - but depending on your Git hosting service, it might also be that you received an error message when trying this command:

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'

This is because GitHub and many other Git platforms expect you to have a "default" branch (which cannot be deleted). And until now, this will most likely be set to "master"! Another mechanism that might be in place is that this branch was set "protected" and thereby cannot be deleted simply from the command line.

In any case, you'll have to hop over to your Git hosting account and change the default branch from "master" to "main" (or/and remove the "protected" state from "master"). Here's an example of how this works on GitHub:

You can now try again - and should be successful in deleting "master" from your remote repository:

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

If other people on your team have cloned one of these repositories, they will have to make a couple of changes on their side as well:

# 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

If, instead of the command line, you're using a Git desktop GUI like Tower, this process is a bit easier. After renaming the branch in the GUI, you can update the remote tracking connection simply from the contextual menu:

Step 4: Updating Your Toolchain

One other thing to keep in mind, however, is your toolchain: if you're using continuous integration tools or similar things, you should make sure to update their configuration. If they depend on an "origin/master" branch, they will complain!

All in all, the process of renaming "master" to "main" isn't terribly complicated, as you've seen. This means there's no reason to hold back: go ahead and give your default branches a better name!

About the Author

Tobias Günther is the CEO of Tower, the popular Git desktop client that helps more than 100,000 developers around the world to be more productive with Git.