Rename Master Branch To Main In GitLab

WHY CHANGE YOUR REPOSITORY BRANCH FROM MASTER TO MAIN?

Git repositories are one of the most popular source tracking tools in use today, and renaming master to main has become more of a spotlight recently due to the master slave type notion that it implies. Many want to follow best practices and trends and change their git repo master to main.

The master slave terminology can sometimes make people feel isolated in the same sense that master slave is sometimes similarly associated with blacklist whitelist. By renaming our git branch to a new main branch, we can result in 'main' as our new branch. We can also update our tracking connection.

Git and the tech community as a whole have recently been transitioning to using the term "main" to describe the new default branch. Other code hosting platforms like GitHub have made the change, and GitLab, another one of the public git hosting platforms, has also made the change as of version 14.0 for self-hosted versions that shipped on June 22, 2021.

GitLab has previously made the Phase 1 change to GitLab.com users. Going from master to main doesn't have to be daunting. In fact, changing our git repositories' master branch name from master to main can be quite a quick and easy process to follow.

STEPS TO RENAME MASTER TO MAIN IN GITLAB

If you are still using "master" as the default Git branch name, then you may be thinking about renaming your branch on existing projects. But how do you do this?

Here we talk about using GitLab to rename master branch to main where you don't even need to create a new git repository.

Step 1) Move master to main by creating a new main branch locally

To rename your local "master" branch on your machine, you'll just need to run a simple one-liner command. This will update your local master branch but not the remote branch. Later on, we also need to look at renaming the remote master branch and changing the default branch name in the git repository.

$ git branch -m master main

Now we can run another one-liner that will tell us if we were successful

$ git status
On branch main
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Now that we can see that we have successfully renamed our local branch, we can do the same on our remote repository, too, as everything we have done so far has not left our computer.

At this stage, we have just updated the current local head branch, but we haven't updated our remote repository. Our existing tracking connection is still pointing to master. This hasn't resulted in a remote renamed branch.

Step 2) Push the new main branch upstream to Gitlab

Renaming a branch isn't that simple. Unfortunately for us, we need to create a brand new branch remotely and then update references to it in places like the default branch, protected branches and perhaps even our GitLab CI file too. This allows us to update our existing projects with a new default branch and change the default branch name.

As long as we are on our "main" branch still as we were before, we can push this new branch to the remote repository.

$ git push -u origin main

At this stage, we should be able to see that now our local repository is up to date with the remote branch name.

$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Step 3) Gitlab Project > Repository Settings > Set Main as Default Branch*

Now that we have a new branch remotely, we need to make sure that we change the default branch in the project settings.

*You'll need to make sure that you have at least Maintainer level access to be able to do this in GitLab.

This will allow us to avoid a remote rejected type error message when deleting our old master branch in our git repository. Head on over to your repository on GitLab.com or self-hosted GitLab instance and go to Settings > Repository.

At the top of the settings page is the Default branch. Select "main" from the dropdown and save changes.

Once we've changed this to main and saved, we can scroll down a little further and make changes to our Protected branches by protecting our new main branch.

Step 4) Gitlab Project > Repository Settings > Add Main to Protected Branches

By default, Maintainers are allowed to push and merge to a protected branch, so you may wish to either select these default settings or specify your own if you use custom settings for your current master branch.

Select the main branch, configure who is allowed to merge & push, and then hit "Protect".

Step 5) Gitlab Project > Repository Settings > Remove master protection

Now that's done, we can go and unprotect our master branch, which is going to allow us to delete it.

"Just click the yellow Unprotect button to the right on master"

This will unprotect what was once our default branch, known previously as the master branch. If we don't perform this step, we'll see a remote rejected error when we attempt to delete this git branch.

Step 6) Finally, delete the origin master branch. Done!

From our local machine, we can issue a delete command to the remote GitLab server to delete the old default branch, which was the master branch.

$ git push origin --delete master

What we should see now is the success in that we've been able to delete the old initial branch called master and finish the process to change over to our main branch.

$ git push origin --delete master
To gitlab.hatchet.com.au:bud/seo.git
- [deleted]         master 

And that's it! We've now been able to update our local branch, change our remote master branch and rename master to main, plus update our local branch and local git repository.

CLEANING THINGS UP IN YOUR GITLAB REPOSITORY

There are many types of different git repositories in use today. For ones that are used by a team of collaborators, you may have other files affected that you need to think of, areas in your code where perhaps an error message or new default needs to be specified.

The main branch might need to be explicitly defined as a git branch in your GitLab CI file or other CI/CD pipeline. This will all depend on your exact setup and are things that this blog post doesn't aim to solve for your unique circumstance. A pull request may be necessary in some cases to replace the term master.