This article was inspired by Scott Hanselman's article about the same topic.
You can also read my blog post on changing the default branch stream upstream in git or changing your default branch everywhere else.
Also while you're here, go follow me on Twitter and signup for my blog
So let's say you're bought in: master is not a great name for the default branch in your repository. Someone somewhere told you it meant "master" as in "master recording" or "master craftsman," and you just went with it like I did for a long time. But now you know, it would make way more sense for it to be named something like "main" or "default" or "develop" or "release"...but how do you make that change?
Making the change in your repository is relatively simple - master isn't really that different than any other branch, it just happens to be the convention we've used for years.
1) Change it locally
To change it, you can use the
move command in git to copy the entire master branch (and it's history) to a new branch like so:
git branch -m master main
You can then push it to your remote repository with:
git push -u origin main
Once you do that, you'll see the option to start a merge request, which we're not going to do because we want
main to become the default branch, not
2) Change it on GitLab
Now that the
main branch exisits on our remote - GitLab - we can change the settings there as well. On your project, go to
Repository. The top section their is called "Default Branch" - expand it to see the drop down where you can select
main instead of master.
Save changes to save it.
Now, the next time someone clones your repository, they will automatically be on the
When they make changes, the link to create a merge request will automatically be pointed at the
3) Other settings
There are other settings that may or may not apply to your repository. When changing the default branch, you should also check:
.gitlab-ci.ymlfile (or other CI configuration) for any hardcoded references to
- Any other third-party integrations that may rely on the name of the branch
4) Remove the master branch
Once you're sure you've gotten any dependencies updated, you can remove the master branch completely. This will help avoid any confusion around what branch is the "default" branch for developers. To remove the branch you can go to
https://gitlab.com/username/repository/-/branches or follow these steps:
- Go to your project and go to
- Click the trash can to the right to delete the branch
- Say "Ok" to the warning about not being able to undo the delete