Rename your Git default branch from master to main (with GitLab screenshots)

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 master

2) Change it on GitLab

Now that the main branch exists on our remote - GitLab - we can change the settings there as well. On your project, go to Settings ➡️ Repository. The top section there is called "Default Branch" - expand it to see the drop down where you can select main instead of master.

Then click Save changes to save it.

Now, the next time someone clones your repository, they will automatically be on the main branch.

When they make changes, the link to create a merge request will automatically be pointed at the main branch.

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:

• Settings ➡️ Repository ➡️ Protected Branches
• Your .gitlab-ci.yml file (or other CI configuration) for any hardcoded references to master
• Any other third-party integrations that may rely on the name of the branch master

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 Repository ➡️ Branches
• Under Active Branches find master
• Click the trash can to the right to delete the branch
• Say "Ok" to the warning about not being able to undo the delete