Moving from Master to Main in Git

Following the recent unrest around race relations after the death of George Floyd one of the lesser-known movements has been to move Git repositories from using master as the default branch to something else, most commonly main. We took the time to transition all of our projects’ repos in this manner. The process we took, which was based on this article, is documented here for anyone else (including our future selves) who want to do the same.

Transitioning a Repository

To start this transition on the local repository on your computer you should make sure to stash any uncommited changes if there are any, then run the following at the command line in your project’s folder and take note of what remotes the repository has for later use:

git remote -v

Then actually move the master branch, here to main:

git branch -m master main

Now it is time to push this new branch to remotes, so for each remote you took note of:

git push -u <remote_name> main

Once the branch is up on the remotes you’ll need to set the new branch as the Main branch. This is in different places on different sites, here are the ones we’ve used:

• For Github: Under Settings for a repo choose Branches and change the Default branch
• For Bitbucket: Under Repository settings choose Repository details, then open the Advanced section and change the Main branch
• For Gitea: Under Settings for a repo choose Branches and change the Default Branch

Back in your local repository you’ll need to delete the master branch from each remote:

git push <remote_name> --delete master

And finally set your head to the appropriate remote, usually origin, as well as pop your stashed chagnes if there were any:

git remote set-head origin -a

Changing Repositories on Other Computers

Once you have transitioned the repository on one computer, all other computers which have cloned it will need to run through the following:

git fetch --all
git remote set-head origin -a
git branch --set-upstream-to origin/main
git branch -m master main
git pull

Changing the Default Branch Name Used for New Repositories

Now that you’ve taken the time to transition existing repositories you’ll want to always use the new name for future projects as well. Unfortunately Git does not have a simple setting to change, there seemed to be one but it didn’t seem to work. So instead you’ll want to make a custom repository template to use.

The first trick here is figuring out where Git is installed. On Macs you may have used Homebrew to install Git. In that case the base tremplate files would be found at /usr/local/share/git-core/templates. The next step will be determining where you want to store your custom template files. I chose ~/.config/git/template/ as my location, but anywhere in your user account would work. Then run the following, replacing the placeholders as needed:

cp -r <system_git_template> <user_git_template>
echo 'ref: refs/heads/main' > <user_git_template>HEAD
git config --global init.templateDir <user_git_template>

When you run git init Git will say it is reinitializing the repository even though it is a brand new repository. This is a side-effect of the reality that your template has a HEAD file in it. Don’t worry about this. But now any new Git repository you make will have the main branch from the start.