DEV Community


Posted on • Updated on

Git: Renaming the "master" branch

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

Top comments (19)

ricokareem profile image
Rico Rodriquez Collins • Edited

When I renamed and pushed the branch main, I needed to manually set upstream so that I did not get "Branch 'main' set up to track remote branch 'master' from 'origin'." So I did it differently.

  1. Make sure master is up to date, then git checkout -b main
  2. git push -u origin main
  3. Log into github/bitbucket/etc and set the Default Branch to main
  4. git branch -d master
  5. git push origin :master

Also, anyone that truly does not believe "that terms such as master, slave, and blacklist are racially-charged or have undesirable connotations", please make sure to add such beliefs to your github profile. Thanks

rexford_gibbs_08389875661 profile image
Rexford Gibbs

Also, too, anyone who (NOT anyone 'that') truly or otherwise does not realize "that terms such as master, slave, and blacklist" exist for more reasons than your simpleminded understanding can deal with - too bad.

garyo profile image

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.

eyqs profile image
Eugene Y. Q. Shen

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!

rhymu profile image

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.

eyqs profile image
Eugene Y. Q. Shen

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

Thread Thread
rhymu profile image

No problem!

samanthalvarner profile image

Thank you for this post. I have used this so many times. The instructions are super easy to follow. I have needed both sets. I have renamed master to main and then worked on repositories where I already had a local repository and someone else renamed it. Just wanted to say thank you.

adampal profile image

For anyone coming to this in January 2021, GitHub have a new feature to make this really easy. Under settings you can change the name of the primary branch. This preserves all open pull requests. When you make the change, they also give you the couple of commands that you need to run to update your local branch to match.

blnx profile image
BlueLynxes • Edited

It's been the 300th time that I try to switch to "master" and it doesn't exist, because some bored idiot needed to do something that day, and decided that changing "master" to "main" for some made up reason was a good idea.

This whole assumption that "master" in the case of Git refers to "master/slave" is wrong, never seen "slave" branches before. Master can have meaning other than a "slave's master".

The "master/slave" architecture of course does exist, so does "master/worker" or other.
And so "blacklist/whitelist" exist... there is only one problem, who decided and when that this was all about black Americans? Are Americans really unable to realize that there is a world and a history outside of their country, and that the language they use comes from there?

Slaves outside of the US have been of every race, in fact, it was very common to enslave people of the same ethnicity, it would happen quite commonly, since they would be close by enough to be enslaved and become a resource to be used, it wasn't even a matter of hate, but of usage. Which is still an unacceptable thing, even thought it is what made us progress at a certain point in history and it engraved in human nature.

So a "master" is not a "white master and a black slave", and Americans being convinced that that's the case, only shows how egocentric they are.

Same goes for blacklists and whitelists, they don't come from allowing white people and not allowing black people. Yes, they are based on the concept that black is scary and bad, want to know why? Because up until not too many centuries ago night (the dark) meant danger, it meant predators, and more recently during the first part of the industrial revolution and previously it meant halting production, since lack of light, you know, makes it hard to work. That is why black is supposedly "bad", it has nothing to do with black people.

But of course, now that everyone magically feels uncomfortable we have to change industry standards right? We have to break scripts, defaults, and the workflow of people.

This is of course a general rant about changing an industry standard, which 2 years later, still comes to bite us in the a**. Of course, renaming branches is and always has been possible, and everybody can feel free to do it.

rexford_gibbs_08389875661 profile image
Rexford Gibbs

Nice post.

tyll profile image
Till Maas

Hi, please add a warning that this will close all open pull requests instead of moving them to the new default branch.

mikelward profile image
Mikel Ward • Edited

I needed to run

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

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

robencom profile image

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

oshgroup profile image

This was really helpful, thank you.

I don't use Github much, so it took me a moment to find where to change the default branch. It is just under Settings>Branches

Some comments may only be visible to logged-in visitors. Sign in to view all comments.