How To: Safely Rename master Branch on GitHub ✊🏾
In the midst of this year's long-overdue support of the Black Lives Matter movement and calls to action in the US and around the world, a new spotlight has been placed on unchecked invocations of racially charged language in the computer science world, no matter how big or small — like the long-standing and, until recently, widely accepted terms "master" and "slave" as an oppressive metaphor for ownership/importance.
When somebody pointed out the negative connotations of Git projects being created with a branch named master by default, and the possibility of this making minorities feel even more unwelcome in an industry already lacking diversity, GitHub CEO Nat Friedman quietly announced a plan to change this on Twitter (ignore the replies for your sanity):
I think many people misunderstood this tweet to mean GitHub will forcefully rename the master branch of all existing projects, which would break millions of programmers' workflows. If anything, it's more likely a name such as main will replace master as the default when creating a new repository, but that change hasn't been made yet. GitLab is also discussing a similar switch to main as the default name. (Ideally, these changes would be made in tandem with the actual Git codebase, too. But this doesn't seem likely.)
Update: GitHub has published more details about their plan to move from
mastertomainand it will indeed be voluntary and configurable. To my surprise, the Git maintainers have also agreed to add ainit.defaultBranchsetting to customize the default branch for new repositories in Git 2.28.
But this means in the meantime, project owners are free to rename their branches as they please — and it's pretty simple to do so, usually with minimal disruption. Some of the biggest OSS projects have already voluntarily done so. Here's how to join them.
1. Move your master branch to main:
...or development, unstable, trunk, live, original; your choice!
We use branch -m to move the branch locally instead of creating a new one with checkout -b like you might be used to.
git branch -m master main
2. Push the new branch to GitHub:
The first command is probably familiar. -u sets the new branch as the local default at the same time, and the second line ensures our local HEAD points to our new branch on GitHub.
git push -u origin main
git remote set-head origin main
You can verify this worked by running git branch -r. You should see something like origin/HEAD -> origin/main.
3. Change the default branch in your repository's settings:
Setting the default branch remotely is the only step that can't be done on the command line (although you can technically use the GitHub API). Head to Settings → Branches on GitHub to change the default branch.
4. Delete the old master branch on GitHub:
We used -m (move) to rename the master branch locally, but GitHub will still have two identical branches at this point (as you saw in the previous step). Deleting it can be a little nerve-racking, so poke around your repository on GitHub and make sure your new branch is there and the commit history is correct.
You can say good riddance to master through the GitHub UI or with this command:
git push origin --delete master
5. Scan your code, scripts, automation, etc. for references to master:
Do a quick search of your codebase for master to manually replace any dead references to it.
Pay attention to CI files — .travis.yml, .github/workflows/, .circleci/config.yml, etc. — and make sure there aren't any external services relying on master being there. For example, I almost forgot to change the branch Netlify triggers auto-deploys from to build this site:
Unfortunately, GitHub won't redirect links containing master to the new branch (as of now), so look for any github.com URLs as well.
Update: GitHub is now redirecting deleted branches to the default branch!
Bonus points:
None of this will work on a brand new repository with zero commits. But we can hack around this limitation pretty easily...
You can create a Git alias in your local environment's .gitconfig to make main the default branch name for new repositories. Git doesn't let you override some native commands like git init, so we'll create our own git new command instead (h/t @johnsyweb):
git config --global alias.new '!git init && git symbolic-ref HEAD refs/heads/main'
This may be a small gesture, but anything we can do to make even one more volunteer feel more welcome in the OSS community will always be worth the extra 10 to 15 minutes of inconvenience on my end. ✊🏾
And while we're at it, Nat... It's time to finally #DropICE. 🧊