Last week a lot of people decided to change their default branch name away from master to use more inclusive language in technology (read Scott Hanselman explain why and how). As we fielded questions from Composer package authors wondering what the impact would be, we have investigated how well Composer supports alternative default branch names, and looked at how we can help people make the transition.

Composer 1.x

In 1.x, master (git), trunk (svn) and default (hg) are special names which are internally normalized to the version number 9999999-dev. This normalization was done initially so that these branches are always sorted to the top, but it does not support other default branch names very well.

You can get around this by defining a branch-alias for your alternatively named default branch - which is recommended anyway if the default branch is not numeric like 3.x or 5.0. If you do that then you can call your default branch anything you want and everything should work.

If people require dev-master and you rename your branch to main or 3.x for example, then those users will have to update their require statement (to dev-main or ^3.0@dev respectively). Otherwise the next update will not find dev-master.

Composer 2.x

In the upcoming Composer 2, master/trunk/default do not have a special meaning anymore, they get normalized to named versions: dev-master, dev-trunk and dev-default, like any other branch foo gets normalized to dev-foo.

In the last couple of days we further improved the experience for alternative default branch names by keeping track of the default name configured in the VCS repository. If you change your default branch to main for example, then master will not have any meaning on your repository. The default branch will receive an alias internally to 9999999-dev unless you configure a branch-alias to a different version yourself.

These changes allowed us to fix a few related issues on https://packagist.org. The default branch is now always shown on top in the version list. There is no more special treatment for master as a branch name, everything should work no matter what you decide to call your default branch.