Master to Main with GitLab
Why
To be honest, this article from Wired gives a good perspective on why you should or should not do this. Read it first.
Read it? Good. Now if you still want to do this, here is a template that we followed for each of our GitLab repos. The same procedure should work for GitLab and GitLab Enterprise.
Before you start: Make sure you have the permissions to do this.
How
Update CI and docs (.gitlab-ci.yml && README.md)
I recommend just running a search-replace through your project and looking for master. Most of those occurrences will probably need to change to main. Noteworthy examples are .gitlab-ci.yml and the Contribute section of your README.md file. I prefer to commit this change directly to master since it will automatically be part of the next step.
Update default branch
This moves the master branch to become main. It automatically deals with the history and reflog for you.
git branch -m master main
git push -u origin mainSet default branch in GitLab
In the repository settings (Settings > Repository), update the Default Branch.
Update protected branches
In the repository settings (Settings > Repository), update the Protected branches. You probably want to have the same settings for main as the old master had. Then set that No one is allowed to push or merge to master. That way you and your colleagues will get errors when old habits kick in and you try to interact with the wrong branch.
Delete origin/master
Now you are ready to delete the master branch from GitLab. Don’t worry, the settings we did above to protect people from trying to interact with master will still be in place. You reach this view via Repository > Branches in the left hand menu.
And then?
Merge requests will need updating. They are, however, safe since master is protected and deleted.
People will need to update their local clone. Luckily, with the protection we put in place, no one will be able to accidentally push any code to the old branch.
git checkout master
git branch -m master main
git fetch
git branch --unset-upstream
git branch -u origin/main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/mainAlternatively, one can just delete the local project and do a fresh clone.
Default branch name for new repos
When you create a new repo in GitLab, the default branch will be master. You can change this default by going to (Admin Area > Settings > Repository > Default initial branch name), and setting your custom name there. This currently only works on GitLab Core and up, but not on GitLab.com.
Bonus: Do you have any separate tools that look at master branches of repositories?
Often branch names will live in CI configurations. Either hardcoded through a UI, or committed to a config file. You will know your tools best so make sure to update any tools outside the repositories as well.
In our case, we have a separate tool that goes through all of our repositories and gets the licencing information from all the imported modules and compiles them into a file that we can publish. This tool just assumes that there is a master branch, so we needed to update this.
Conclusion
This is not a big nor difficult change. If you have many repos then this is a bit of a rinse and repeat process, and can probably be scripted using GitLab’s API.
All cred goes to Scott Hanselman who did all the heavy lifting with this information. I just added some information specific to GitLab. Make sure to check out his article on renaming your default git branch from master to main.
