Git: Renaming the "master" branch

rhymu8354 profile image rhymu8354 Updated on ・2 min read

Recently, the CEO of GitHub responded to a Tweet about renaming default Git branches from master to main, saying, "It's a great idea and we are already working on this!" Now, you may or may not believe that terms such as master, slave, and blacklist are racially-charged or have undesirable connotations nowadays. However, I hope we can all agree that it's always good to have the know-how and the tools to be able to change the names we use. That goes for branch names as well.

Renaming Git branches isn't that difficult. However, it gets a tad harder when you want to rename it both locally and upstream. It gets even trickier for the default branch, because of an interesting fact about Git that I consider to be a design flaw: Git has no built-in method of changing the default branch remotely. It's up to the developer to go to where it's hosted (GitHub, GitLab, Bitbucket, etc.) to change it.

Therefore, I spent some time today coming up with a procedure for renaming branches, which I then used to rename around 60 public and private Git repositories that I maintain. I thought I would post a write-up here about it, in case anyone is interested or needs to learn it themselves:

  1. Rename your local branch.

    git branch -m master main

  2. Push renamed branch upstream and set remote tracking branch.

    git push -u origin main

  3. Log into the upstream repository host (GitHub, GitLab, Bitbucket, etc.) and change the "default branch".

  4. Delete the old branch upstream.

    git push origin --delete master

  5. Update the upstream remote's HEAD.

    git remote set-head origin -a

That's covers it on your end and where your repository is hosted. Now what do you have to do if it's someone else's repo which renamed a branch, and you're left holding a "dangling" reference (so to speak) to a remote branch that no longer exists?

If you know the branch was renamed, there's nothing to fear. The following steps will get you back on track:

  1. Fetch the latest branches from the remote.

    git fetch --all

  2. Update the upstream remote's HEAD.

    git remote set-head origin -a

  3. Switch your local branch to track the new remote branch.

    git branch --set-upstream-to origin/main

  4. Rename your branch locally.

    git branch -m master main

That's it! Note that it gets much simpler if you have no remote/upstream. It's just git branch -m master main to rename a branch. The other commands are all concerned about matching local branches to remote ones (via tracking branches) and updating the HEAD reference to point to the "default" branch.

[EDIT: @eyqs made a neat tool to automate this process, including changing the default branch on GitHub so you don't have to do it by hand! Of course, as always, use at your own risk, read the code yourself first to make sure you can trust it, etc. eyqs.ca/tools/rename/]

Posted on Jun 10 by:

rhymu8354 profile



Long time programmer who enjoys reinventing the wheel


markdown guide

I made a tool that calls the GitHub API and automatically changes the default branch for all of your GitHub repositories remotely. Then all you have to do is pull the changes into your local repositories. Let me know what you think, and if you like it, please add it to your blog post! eyqs.ca/tools/rename/


The tool you wrote is very neat! I thought about making a tool that just does the "patch" part (changing the default branch) but in the end I opted to just change them all manually since it didn't take long. However, I'm sure your tool could be handy for others, especially if there are a lot of repos to go through.


Thank you for the kind words! Do you mind if I add your reply as a testimonial on the project page?


Thanks for this -- nice & easy to follow.
After I did this, on my other clones of the repo, after following your instructions, I needed to do git remote prune origin to remove refs to the stale origin/master.


I needed to run

git fetch --all --prune
git branch -d master

on my other checkouts to make the old branch name go away.


Good article. Good information.
I agree 100% with you: " However, I hope we can all agree that it's always good to have the know-how and the tools to be able to change the names we use. "


Who the fuck cares, really? It's been master ever since. Ya all sensitive fuckers need to grow up.


I like you :)
We should probably go through all history and check for every implied wording. And have a good old book burning.
World: youtube.com/watch?v=bg06R8cnnYE


Imagine conflating renaming a branch to book burning

Sloan, the sloth mascot Comment marked as low quality/non-constructive by the community View code of conduct

It's not very productive to follow all these whims of people. What will it be next time? Who will be upset by renaming master to main?
Can you even imagine the cost of a change like that? And how much that will break?
Wont ever partake in something silly like that.
Who has ever mixed the thought of the master branch with a slave owner? Hands up.
The world is crazy anxious now.
Have never had problems working with black people. Have not even thought of it. Until blm became terrorists.
I love learning about real history. And git history have saved all of our butts sometime I think :)