DEV Community

loading...

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

Discussion (15)

pic
Editor guide
Collapse
garyo profile image
GaryO

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.

Collapse
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

Collapse
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! eyqs.ca/tools/rename/

Collapse
rhymu8354 profile image
rhymu8354 Author

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.

Collapse
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
rhymu8354 profile image
Collapse
adampal profile image
adampal

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.

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

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

Collapse
oshgroup profile image
PEAcademy

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

Collapse
robencom profile image
robencom

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

Collapse
dretax profile image
Comment marked as low quality/non-constructive by the community. View Code of Conduct
DreTaX

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

Collapse
kewi69 profile image
Comment marked as low quality/non-constructive by the community. View Code of Conduct
Kenneth Wilhelmsson

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

Collapse
quii profile image
Chris James

Imagine conflating renaming a branch to book burning

Collapse
kewi69 profile image
Comment marked as low quality/non-constructive by the community. View Code of Conduct
Kenneth Wilhelmsson

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 :)