Recently, in the world there has been a push for change. Specifically, in the technology industry there have been efforts to change our rhetoric to make it more inclusive and accessible.

Now, as this is a technical blog, I will refrain from sharing my opinions here (though if you contact me, I would be happy to discuss in another setting). This blog post will cover one place where the industry is making a change: git default branch naming.

As long as I have been using git, the default branch name has been “master”. Suffice it to say, this is a non-inclusive term, which is the reason why many are changing their default branch. In fact many organizations are changing their tools to make inclusive naming the standard.

For instance the Software Freedom Conservancy has said about branch naming:

“We support and encourage projects to switch to branch names that are meaningful and inclusive, and we’ll be adding features to Git to make it even easier to use a different default for new projects.”

Along those same lines, GitHub has created a repository to visibly track their progress with branch naming tools on their site.

What is the branch name anyway?

Assuming you have now decided to rename your default branch, the next task is choosing the right name. But how?

Many will recognize Juliet’s famous words from William Shakespeare’s Romeo and Juliet:

“What’s in a name? that which we call a rose
By any other name would smell as sweet;
So Romeo would, were he not Romeo call’d,
Retain that dear perfection which he owes
Without that title. Romeo, doff thy name,
And for that name which is no part of thee
Take all myself.”

If you will allow me to apply Juliet’s metaphor to this modern context: I would argue that the new name of the branch doesn’t matter so much as long as it is inclusive and accessible. Regardless of name, it will serve the purpose of default git branch.

That said, I (and my team) have chosen to use main as the default branch in our repositories. The main reason for this decision is consistency with decisions made by others and tools that we use.

Specifically, GitHub has said:

“main is the most popular replacement for master that we’re seeing across GitHub. We like it because it’s short, it keeps your muscle memory intact, and it translates well across most languages. We’re using main for our newly-created repositories and for the repositories we’re moving now, like dependabot-core.”

Thus, all of the examples in this post will assume main as the new default branch, but feel free to replace that with whatever name you choose.

What is the technical impact?

As most technologists have discovered, renaming things in software is seldom as simple as thinking of a new name and changing our vocal rhetoric. There is often technical side effects involved.

Depending on your context this list may not be complete; however, these are the locations where we found changes were needed after the renaming process:

• Local development machines
• Pull Requests
• Forks of repositories
• CI pipelines
• CD pipelines
• Onboarding scripts for contributers
• Automation toolsets
• Documentation

What is the process for renaming?

Steven Mortimer wrote a wonderful article detailing the steps of renaming a branch in git. It formed the basis for a script I wrote to make the process easier across the many repositories in which I work. For details on these steps please refer to his article or see the script below.

But before you try this out yourself, note that if you are using GitHub they have made the process a lot easier since my team first attempted it. Using the renaming tool on their website not only removes the need for most of the manual steps but also handles things such as pull requests and forks. The process is as easy as clicking the edit icon next to your default branch in the branch list, enterning a new name and clicking rename branch. Then follow a few manual steps that the site will provide to you. See here for their official documentation or here to follow the status of what GitHub is doing to improve the process of renaming branches.

For those of you not using GitHub, here’s the scripts we used as promised. In between the two scripts, you will need to login to your git server to:

• change the default branch to the new branch (GitHub | GitLab)
• ensure that the former default is not protected (GitHub | GitLab)

#!/usr/bin/env bash
set -x

git checkout master

remote=$(git remote show)

git pull
git branch -m master main
git push -u $remote main
git symbolic-ref \
    refs/remotes/$remote/HEAD \
    refs/remotes/$remote/main
git branch -a

#!/usr/bin/env bash
set -x

remote=$(git remote show)

git push $remote :master
git remote prune $remote
git branch -a

How about those side effects?

Handling the side effects can vary drastically depending on what tools you, your team, and your organization are using, but here are some general tips:

CI/CD

In your CI/CD pipelines look for places where names of branches have been explicitly specified. For example, in TeamCity check your “Default Branch” setting in your VCS Root. In GitLab pipeline as code look for blocks such as rules, needs, includes, refs where you may have hard coded branch names. GitLab provides predefined variables such as $CI_DEFAULT_BRANCH and $CI_COMMIT_BRANCH to make dynamically working with branches easier.

Scripts

Look for hard coded branch names in automation run locally: Makefiles, npm scripts, shell scripts, build scripts, etc… Perhaps adjust it to use the current branch or to query the default branch from a remote.

Documentation

Read your documentation—especially contributor documentation. Ensure that newcomers to the project know what to expect in terms of branching strategies and branch protection. Make sure that previous/other contributers know how to migrate. Changing the default branch on git and on your local machine will not change it on the machines of others. I offer the following script to others based from the instructions provided by GitHub after renaming a branch on their website.

#!/usr/bin/env bash

remote=$(git remote show)

git branch -m master main
git fetch $remote
git branch -u $remote/main main

Pull requests/forks

Depending where you host your source code, how you handle pull requests and forks when changing branches can vary drastically. If you have only a few pull requests/forks, this may be a non-issue, but if you have a large number, manually updating them could be out of the question. GitHub handles this for you if you rename using their UI tool, but not all providers do. I would recommend trying out renaming on a small/low impact repository first. Or create one just for testing the behavior.

That’s it!

Regardless of your stance on recent events and specifically renaming branches, I hope that the technology industry can be a welcoming and comfortable, yet challenging and exciting environment for all who wish to learn. Further, I hope that this article was able to answer some of the technical questions you may have as you explore what role git branches play in your environment, organization, etc…