Harry R. Schwartz

I’ve been renaming the default git branches on my personal projects from master to main. If you’re interested in doing something similar, I’ve compiled some instructions to help make that easy.

• Reconfiguring an existing repository
• Reconfiguring GitHub
• Reconfiguring all new repositories

Reconfiguring an existing repository

This one’s simple. Checkout master, rename it to main, and push main up to your remote (probably “origin”):

$ git checkout master
$ git branch -m master main
$ git push -u origin main

Reconfiguring GitHub

For each project, visit “Settings→Branches” and switch the default branch to main.

This may have repercussions! You’ll want to update any services that integrate with your project that depend on the presence of a master branch.

Furthermore, if you subsequently delete the master branch, be aware that any open PRs against master will be automatically closed!

Reconfiguring all new repositories

I’m lazy and forgetful, so when I run git init in a new project I’d like my default branch to already be set to main.

For git 2.28 and later:

As of version 2.28, git supports an init.defaultBranch option. If you’re using that (check with git --version), you can change your default branch with:

$ git config --global init.defaultBranch main

Or, equivalently, you can manually edit your ~/.gitconfig with:

[init]
  defaultBranch = main

…and you’re all set!

For earlier git versions:

However, if you’re using an older version of git, you can achieve the same result with these older instructions.

“Setting a default branch” is equivalent to ensuring that HEAD refers to main instead of master, and the value of HEAD is defined in .git/HEAD. So, every time we initialize a new repository, we’d like to create a .git/HEAD file that points to the correct branch.

We can do that by defining (or modifying) a “template.” When we create a new repository with git init, git copies a few files into the newly created .git directory—those files comprise the template.

The default template is located at /usr/share/git-core/templates, but we can define our own custom template (with a custom HEAD file) instead. So let’s do that!

First, we’ll create a directory containing our new template:

$ mkdir ~/.git-template

Next, we’ll populate ~/.git-template/HEAD with a ref pointing to main:

$ echo "ref: refs/heads/main" > ~/.git-template/HEAD

Finally, we need to ensure that our new template is copied into each new repository. Edit your ~/.gitconfig or ~/.config/git/config file to include:

[init]
  templateDir = ~/.git-template/

To test it out,

$ mkdir ~/test-default-branch
$ cd ~/test-default-branch
$ git init
$ cat .git/HEAD
ref: refs/heads/main
$ git status
## No commits yet on main

Looks like it worked!

Note that if you’ve already got a default template set up you’ll just need to create or modify the HEAD file.

I’ve started keeping my git configuration under ~/.config/git, so some of the file names are a bit different, but you can still take a look at the commit to my dotfiles that does all this.