The new Git default branch name

Note: We have added release 13.12 to our release schedule. 13.12 is due to ship on 2021-05-22. This will cause the next major release 14.0 to ship in June instead of May as originally stated. The below content has been updated to reflect the new release date for 14.0 of 2021-06-22.

Every Git repository has an initial or original branch, which is the first branch to be created when a new repository is generated. Historically, the default name for this initial branch was master. This term came from Bitkeeper, a predecessor to Git. Bitkeeper referred to the source of truth as the "master repository" and other copies as "slave repositories". This shows how common master/slave references have been in technology, and the difficulty in knowing how the term master should be interpreted.

A more descriptive and inclusive name

The Git project maintainers, in coordination with the broader community, have been listening to the development community’s feedback on determining a more descriptive and inclusive name for the default or primary branch and offering users options to change the name of the default branch name (usually master) of their repository. There have already been significant steps toward this goal:

• Git 2.28.0, released in July 2020, introduced the init.defaultBranch configuration option, which allows Git users to define and configure a default branch name other than master. In June 2020, the Software Freedom Conservancy released a statement summarizing why the default term master is offensive to many users because of its history.

• Git maintainers are actively working toward a permanent change for the default name from master to main. You can read more about this change on this post from the Git mailing list. A large part of this effort involves updating all existing tests in the Git project.

Changing GitLab's default branch name

GitLab has already introduced changes that allow users to change the default branch name both at the instance level (for self-managed users) and at the group level (for both SaaS and self-managed users). To further align with the community, we will make the following changes in the upcoming releases:

1. Default branch name changes for GitLab.com and self-managed users: When creating a new project in GitLab, the default branch name will change from master to main. We are planning to implement this change in two phases:

   • Phase 1 (GitLab.com): We plan to update GitLab's underlying Git version to 2.31.0 as part of GitLab’s 13.11 release, shipping on April 22, 2021. We will additionally change the default branch name on GitLab.com from master to main on May 24th, 2021.

   • Phase 2 (Self-managed): We will change the default branch name from master to main for self-managed GitLab as part for our next major release 14.0, shipping on June 22, 2021. Any project created in GitLab post 14.0 will use the new default. This does not affect existing projects.

   • Action required: When upgrading a self-managed instance to GitLab 14.0, new projects created via the GitLab GUI will use main as the default branch name. If your project is running CI/CD jobs configured in another project, hard-coded references to the master branch will need to be updated to use either main or to use a default branch name CI/CD variable, such as CI_DEFAULT_BRANCH. You can continue to use master by configuring a custom default branch name.

2. Default branch name change for the GitLab project (and its related projects): The GitLab project and its related projects will change their default branch name from master to main. Some projects have already been updated (for example GitLab Shell) and we plan to update the rest between now and the release of 14.0 on June 22, 2021.

   • Action required: If during the switchover you created a contribution for the GitLab project and are still using the master branch locally, you will need to rebase your changes prior to pushing to consume the new default branch name of main.

Please note this will only affect new projects created in GitLab. Existing projects will not be affected. You can learn more about the change in the default branch rename epic.

We welcome the use of main as a more inclusive default branch name and are happy to see that our peers at GitHub and Atlassian also support this change.