‘master’ has always been a poor branch name

Recently I was scrolling through my twitter timeline when I encountered this tweet by Fabien Potencier:

Fabien eloquently describes something that suddenly clicked with me; master has always been a poor choice of name.

With the current state of affairs, people have been reviewing the names that we use on a daily basis. And the word master is contentious depending on the context in which you use it.

In the context of GIT and how the name itself can be considered harmful is much better described in this blog post: https://boleary.dev/blog/2020-06-10-i-was-wrong-about-git-master.html; I am going to zoom in on Fabien his tweet and why I think this alone would be a good enough reason, even while considering the potential harm that the meaning of the name does.

What’s wrong with ‘master’?

Consider your favourite branching strategy, I don’t think it even matters much which one that is, and then consider what the name master means in the bigger picture and how it relates, or doesn’t, to the other branch names.

As an example, I am going to take a look at how we have done it in phpDocumentor. In phpDocumentor, we use trunk-based development and the following branching strategy:

  • we commit everything for the newest release to the mainline, currently still called ‘master’
  • For every minor release, we make a new branch with the name of that release. For example 3.0 (to be released)
  • For every build release, we create a tag with the build number from the mainline.
  • When working on long-living branches for a specific larger feature (try to avoid this!) we prefix the branch with feature/ and provide a describing name for the feature that we are making.

Now, take a step back and let’s look at the names more closely: master, 3.0, 3.0.1 and feature/my-awesome-contribution. Except for master, all these names are expressive and describe what the branch is about.

This is the whole point: master as a term is meaningless in your project.

Ok, then what?

I challenge you to find a better name for that branch, a name that truly expresses what it is in it. Github floats the name main; which, if you ask me, is from a point of expressiveness equally bad. Surely better names are to be had?

For phpDocumentor, we have settled with Fabien’s strategy for Twig. We have started to rename our master branches to match the major version that we are working on followed by a .x to indicate it is the latest for that version. So, as an example: we are now working on phpDocumentor version 3; so master will become 3.x.

Caveat: we are rolling out this change gradually to monitor the effect on various tools that we have and tools used by the community.

There have been various suggestions that came by, including trunk (from the good old SVN days), production for branches to go directly to production, default as a one-to-one replacement and many more. Which you pick is up to you; I can only recommend picking something that is expressive and really describes what is on that branch.

Going forward

I know this change will inconvenience people. Some projects have their tooling based on the master terminology or depend on other packages’ master branch (don’t if you can avoid it!). That is a price that we need to pay for improving our work and our world.

Update: on Twitter Andreas Heigl mentioned that some tools indeed have issues with the absence of a master branch. As for the status of Composer, I can refer to this blog post by Jordi: https://blog.packagist.com/composer-and-default-git-branches/

As from this day, I intend to make an effort to name every branch with clarity and steer away from the name master whenever I have influence over it. I know I will stumble and fail in the future, but I will persevere. As this change will make branch naming clearer, will hurt fewer people and I have good hopes that in the future we will not use a default name anymore but when you start a new repository, you will be asked:

“What is the name of your first branch?”