A step-by-step guide for your company's Git master to main migration

On Juneteenth, B12’s engineering team migrated its default git branch names to main , removing the problematic term master . Here’s the planning document we used, including internal messages and instructions for you to do the same.

Problem

The terms we pick for our tools matter, and our current default branch name of master is problematic. The word master is too closely related to the word slave , a practice that goes against B12’s values. For more information, see this helpful writeup from the IETF .

Slack announcement

Hello @engineers! The terms we pick for our tools matter, and our current default branch name of master is problematic. The word master is too closely related to the word slave , a practice that goes against B12’s values. What does this mean for you?

• I tested a <repository name> conversion over the weekend with seemingly no impact on our infrastructure.
• Over the course of the next week, we’ll convert the rest of our repositories.
• You can find a full timeline of conversions here, along with the owner of the conversion: <link to the timeline section>
• The <repository list> repositories are the most important ones to migrate carefully. These repositories have a lot of open PRs against master , which block us from being able to delete the branch. To get around this, we’ll freeze all merges to master on <day> at <time>. We’ll create a main branch that will serve as the default branch. You will have until <next day> at <time> to change any of your PRs’ base to main (in the PR, click Edit and select base: main ). Any open PR with a master base on <next day> at <time> will be closed. We will then delete master .
• If you’d like to volunteer to convert a repository, add your username to the timeline along with the repository and a name.

How to convert a repository

The new name of our default branches will be main .

For any repository, here are the steps we’ll follow to migrate it (documented on <repository you tested it on>, which we’ll test for a week and then implement across our branches).

• Grab the no_masters.sh script
• Make sure the repository is in a clean state (i.e., on the latest commit of the main branch, a clean `git status`).
• Make sure your Github token doesn’t end up in your bash history
  set +o history
• Run the script
  ./no_masters.sh -u YOUR_USERNAME -o YOUR_ORGANIZATION -t THE_TOKEN main REPO_FOLDER/
• Inevitably, master will be protected, and not get deleted. Head to https://github.com/b12io/REPO_FOLDER/settings/branches and replace it with main , and set main as a protected branch.
• <someone should automate this, but it’s sort of rewarding to do manually :)> Edit every open PR to point at main by clicking its Edit button and selecting a new base.
• Grep the codebase for master , and submit a PR that replaces it with main . In particular, deploy scripts and other functionality will require an update.
• Head to https://github.com/b12io/REPO_FOLDER/branches and manually delete master .
• Fix any issues that arise in continuous integration or other automation.

Timeline

Create as many bullets as you have repositories.

• [owner name] repository name: date we’re converting

Thank you

Thank you to Margaret for getting the idea in my head, Hilary for pointing to a script, Adam for writing it, and Daniel and Nitesh for providing feedback on this document!