Why GitHub’s default branch keeps ghosting you

Renaming ‘master’ to ‘main’ is harder than you think because there is no such thing as a default branch in git

Dan Lester
7 min readApr 16, 2021


Many GitHub projects have recently performed the task of changing their ‘master’ branch to ‘main’. And GitHub has even set the worldwide default branch as ‘main’ for new repos. There are many great guides to help with the migration such as this one, and the procedure can happen pretty smoothly for an existing repo.

But things start to go wrong if you create new repositories, especially if you create lots of new repos, perhaps using GitHub’s API. We are doing this on the QHub project — it’s a tool to easily set up the full continuous-deployment pipeline, including GitHub actions, for your own managed Kubernetes cluster running a JupyterHub environment. So we automate the creation of lots of new repos.

Photo by Toa Heftiba on Unsplash

Sure, there is an option in GitHub to set the default branch for a new repo, and there is even more control within an organization.

But even when this is set to ‘main’ it doesn’t seem to help. Repos keep appearing with ‘master’ as the default branch.

The reason is that there is actually no such thing as a ‘default branch’ in git.

Empty GitHub repos are really very empty

Let’s run some tests to see what’s really going on. First, create a completely empty repo (don’t add any automatic README files etc or that will ruin it).

So GitHub knows this is an empty repo and shows us some ideas for populating it:

But keep it empty and see what happens on the command-line.



Dan Lester

Entrepreneur building tools for data scientists: containds.com

Recommended from Medium