How to change the name of the principal Git branch

Photo by Muneeb Qureshi on Unsplash

I’ve got a new computer, and I installed Git on it. Then I decided I had to upgrade Git on my other computer, which had version 2.14. There have been a lot of significant changes with version 2.32.

One of these changes got me to thinking about something I’ve taken for granted for a few years: the name of the default branch in a repository.

For almost as long as I’ve been using Git and GitHub, and long before, the default branch of a repository is called “master.” I never thought I would want to change that branch name.

In recent years, there has been talk that the branch name “master” is problematic because of the suggestion of the master-slave relationship. Both “master” and “slave” are used in some contexts in computer science.

That wasn’t the original intent for Git and GitHub, which use the term “master” but not the term “slave.” Still, that association affects the perception of Git and GitHub.

If there is a way that I can change the principal branch name of my Git repositories to something that won’t offend anyone, I should make that change.

I have some privilege which does shield me from considerations like this. Frankly, if it hadn’t been for going through the Git installation on one computer and an upgrade on another, I might not have given this issue any more thought.

Depending on the options you choose when installing Git or upgrading to the latest version, Git will make new repositories with a default branch name that you specify during the installation or upgrade.

The Git installer suggests names like “trunk” for the principal branch, and also that many teams have already made the change away from “master.” So I chose “main.” Easy enough.

Note that your older repositories won’t be changed unless you consciously make that change for each of them. That might be a little difficult.

Changing the default branch name on a repository to something more “inclusive” like “main,” “base” or “default” won’t resolve any of the social injustices of our world.

But at least it gets us thinking about how certain prejudices have been unthinkingly codified into our culture, and unthinkingly woven into things we take for granted, like version control software.

Hopefully I don’t have to convince you to make this change for both your new repositories and your existing repositories. But you might worry that such a change for an existing repository could wipe out the repository’s history.

And even if you are not worried about that, there are a lot of questions: How do I even do that? What complicated sequence of Git commands do I have to go through to make that change? How will this affect my team and people who have forked my repositories?

Before you make this change for an existing repository, I recommend you make sure that your “working tree” is “clean,” nothing to commit, nothing untracked.

If you have collaborators on the repository, let them know you’re about to make this change. Also check that there are no programs relying on specific branch names.

I decided I would make this change for my one QBasic repository first. It’s for a QBasic program I wrote many years ago, before I even knew about version control. The only history on the repository is the initial commit and a couple of edits to the Read Me file. So no big loss if that gets erased.

The steps for changing the branch name

As with anything involving Git, it’s a good idea to check the Git status on your local machine.

C:\Users\AL\Documents\QBasicPrograms\aster7>git status
On branch master
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean

But also check all the branches in the repository. In this example, the repository only has one branch, the one I want to rename.

C:\Users\AL\Documents\QBasicPrograms\aster7>git branch
* master

Now let’s make the move.

C:\Users\AL\Documents\QBasicPrograms\aster7>git branch --move master main
C:\Users\AL\Documents\QBasicPrograms\aster7>git branch
* main
C:\Users\AL\Documents\QBasicPrograms\aster7>git status
On branch main
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean

This shows the change at this point is strictly local. To make this even clearer, use the All option on the Branch command.

C:\Users\AL\Documents\QBasicPrograms\aster7>git branch --all
* main
  remotes/origin/HEAD -> origin/master
  remotes/origin/master

Now we need to push the main branch to the remote repository.

C:\Users\AL\Documents\QBasicPrograms\aster7>git push --set-upstream origin main
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'main' on GitHub by visiting:
remote:      https://github.com/Alonso-del-Arte/aster7/pull/new/main
remote:
To https://github.com/Alonso-del-Arte/aster7.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.
C:\Users\AL\Documents\QBasicPrograms\aster7>git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
C:\Users\AL\Documents\QBasicPrograms\aster7>git branch --all
* main
  remotes/origin/HEAD -> origin/master
  remotes/origin/main
  remotes/origin/master

Both files in the main branch show all the history I was expecting to see: the initial commit from 2019, an edit in 2019 and an edit from last week.

At this point the master branch is still present on the remote repository. Before we delete the master branch, let’s go through this checklist of things that might rely on or refer to specific branches:

• Test-runner configuration files
• Build scripts
• Release scripts
• Unresolved pull requests
• Documentation

None of these apply to my old QBasic project.

Once you’re sure the things on the checklist won’t be negatively impacted by the change, go ahead with the deletion:

C:\Users\AL\Documents\QBasicPrograms\aster7>git push origin --delete master
To https://github.com/Alonso-del-Arte/aster7.git
 ! [remote rejected] master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'https://github.com/Alonso-del-Arte/aster7.git'

Oops, something went wrong. I needed to go on GitHub and change the repository’s settings, specifically the branches settings. According to GitHub, I don’t have any branch protection rules defined on the master branch.

Still, GitHub won’t let me delete the default branch, and right now that’s the master branch. I consider that a branch protection rule. Go to the repository’s setting and click on the Branches category.

Under the default branch heading, there should be a little two arrows icon, which I’ve highlighted in yellow in the screenshot below:

I should’ve taken that screenshot before I made the change. Oh well. When you click on the two arrows, a box will come up in which you choose which branch you want to be the default branch.

When you select the new default branch, you will have an opportunity to review the change in your mind once more and back out if you neglected any important preparation.

The pencil icon to the left of the two arrows icon is to edit the branch name. I just realized that I didn’t need to clone this particular repository to my local machine, I could’ve made the change on GitHub in much fewer steps.

Anyway, Git should let me delete the master branch now.

C:\Users\AL\Documents\QBasicPrograms\aster7>git push origin --delete master
To https://github.com/Alonso-del-Arte/aster7.git
 - [deleted]         master
C:\Users\AL\Documents\QBasicPrograms\aster7>git branch --all
warning: ignoring broken ref refs/remotes/origin/HEAD
* main
  remotes/origin/main

Uh oh, something’s wrong here. I need to fix the broken head reference.

C:\Users\AL\Documents\QBasicPrograms\aster7>git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

You won’t see anything in response to this, just a new command prompt, so you should check the branches and status.

C:\Users\AL\Documents\QBasicPrograms\aster7>git branch --all
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
C:\Users\AL\Documents\QBasicPrograms\aster7>git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

Okay, one down, four dozen to go.

The steps again, for practice

Let’s walk through another repository for the sake of practice. I’m going to choose a repository with a principal branch and a gh-pages branch, Wacky Fill-Ins (kind of like Mad Libs).

First, check the status and branches. If you’re not already on the master branch, switch to it.

C:\Users\AL\Documents\Web Pages\wacky-fillins>git status
On branch master
Your branch is up to date with 'origin/master'.
nothing to commit, working tree clean
C:\Users\AL\Documents\Web Pages\wacky-fillins>git branch --all
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/gh-pages
  remotes/origin/master

Then rename the principal branch on your local machine.

C:\Users\AL\Documents\Web Pages\wacky-fillins>git branch --move master main
C:\Users\AL\Documents\Web Pages\wacky-fillins>git branch --all
* main
  remotes/origin/HEAD -> origin/master
  remotes/origin/gh-pages
  remotes/origin/master

Push the change to the remote repository.

C:\Users\AL\Documents\Web Pages\wacky-fillins>git push --set-upstream origin main
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'main' on GitHub by visiting:
remote:      https://github.com/Alonso-del-Arte/wacky-fillins/pull/new/main
remote:
To https://github.com/Alonso-del-Arte/wacky-fillins.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Now go on the GitHub website and change the default branch for the repository. As far as I can tell, there’s no way to do this from the command line. In this second example, we could very well decide to make the gh-pages branch the default branch. But I go ahead with main.

Next, change the head reference to the main branch.

C:\Users\AL\Documents\Web Pages\wacky-fillins>git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
C:\Users\AL\Documents\Web Pages\wacky-fillins>git branch --all
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/gh-pages
  remotes/origin/main
  remotes/origin/master

I’m going to hold off on deleting the master branch because I haven’t told the collaborator about this change yet.

Summary

The steps to change the name of the principal branch from “master” to “main” are:

1. Check that you are on the master branch, that there are no pending commits nor pull requests.
2. If applicable, run all the test suites and check the build and release scripts, and the documentation for references to the master branch, and talk it over with your team or collaborators.
3. Rename the master branch on your local machine with the command git branch --move master main.
4. Push the new main branch to the remote repository with the command git push --set-upstream origin main.
5. Go on the GitHub website to change the default branch.
6. Fix the head reference with the command git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main.
7. If you’re absolutely sure, delete the master branch with the command git push origin --delete master.

But if, for whatever reason, you’re confident the repository only exists as a remote repository on GitHub, you can simply rename the master branch on GitHub.

However, even if the repository shows zero forks, it’s still possible that some people have pulled it in to their local machines. If they have no pending changes, they can simply delete it from their local machines and pull it back in anew.

Otherwise, they can use these commands:

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

This change doesn’t compensate for the injustice of slavery. But it shows a willingness to listen to the feelings and perceptions of people with less automatic privilege, and to prioritize those over one’s own personal convenience. That’s a step in the right direction, I think.

I have changed some of my repositories, but I haven’t changed all of them. I’ve set myself a goal of changing all of them before the next Hacktoberfest. Or if not, at least the ones I haven’t marked as deprecated.

I’d love to hear from you on this in the comments. Maybe you know an even easier way to make this change.