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:
-
Rename your local branch.
git branch -m master main
-
Push renamed branch upstream and set remote tracking branch.
git push -u origin main
Log into the upstream repository host (GitHub, GitLab, Bitbucket, etc.) and change the "default branch".
-
Delete the old branch upstream.
git push origin --delete master
-
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:
-
Fetch the latest branches from the remote.
git fetch --all
-
Update the upstream remote's HEAD.
git remote set-head origin -a
-
Switch your local branch to track the new remote branch.
git branch --set-upstream-to origin/main
-
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/]
Top comments (19)
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.masteris up to date, thengit checkout -b maingit push -u origin mainmaingit branch -d mastergit push origin :masterAlso, 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
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.
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 originto remove refs to the staleorigin/master.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?
No problem!
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.
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.
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.
Nice post.
Hi, please add a warning that this will close all open pull requests instead of moving them to the new default branch.
I needed to run
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. "
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.