U-M GitLab: Renaming 'master' Branch in Git Repository

Environment

U-M GitLab

Issue

How do I rename the "master" Branch in a Git Repository?

Resolution

Renaming the Local "master" Branch

The first step is to rename the "master" branch in your local Git repository:

$ git branch -m master main

Then, check to see if the rename has worked as expected:

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

nothing to commit, working tree clean

The local branch has been renamed - but we now need to make some changes in the remote repository in U-M GitLab as well.

Renaming the Remote "master" Branch in U-M GitLab

In this second step, we'll have to create a new branch on the remote named "main" - because Git does not allow one to simply "rename" a remote branch. Instead, we'll have to create a new "main" branch and then delete the old "master" branch.

Make sure your current local HEAD branch is still "main" when executing the following command:

$ git push -u origin main

We now have a new branch on the remote named "main". Let's go on and remove the old "master" branch on the remote:

$ git push origin --delete master

Depending on your exact setup, this might have worked and the renaming is successful. In many cases, however, you will see an error message like the following one:

To https://gitlab.umich.edu/example/sample-repo.git
! [remote rejected]   master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'https://example@gitlab.umich.edu/example/sample-repo.git'

U-M GitLab, like other code-hosting platforms, automatically defines a "default" branch, and deleting this branch is not allowed. Additionally, your old "master" might be set as "protected". You'll need to resolve this before you can go on. Here's how to do this in U-M GitLab:

Unprotect Existing "master" Branch

1. Log into U-M GitLab, and select the repository you'd like to change
2. In the left-side navigation, under "Settings", select "Repository"
3. Expand the "Protected Branches" section, and select "Unprotect" on the 'master' branch

Protect New "main" branch

1. In the same repository settings page as above, in the "Protected Branches" section, fill out the form to protect your new "main" branch, and click the green "Protect" button
2. Verify on page refresh that your "main" branch is listed properly as "protected"

Set New Default Branch

1. In the same repository settings page as above, in the 'Default Branch" section, switch the dropdown menu from "master" to "main", then click the green "Save Changes" button
2. Verify on page refresh that the default repository branch is "main" by expanding the "Default Branch" section again

Once this is complete, you can attempt to delete the "master" branch in U-M GitLab again.

$ git push origin --delete master
To https://gitlab.umich.edu/example/sample-repo.git
 - [deleted]           master

Managing Additional Checkouts

If other people on your team have local clones of the repository, they will also have to perform some steps on their end:

# Switch to the "master" branch:
$ git checkout master

# Rename it to "main":
$ git branch -m master main

# Get the latest commits (and branches!) from the remote:
$ git fetch

# Remove the existing tracking connection with "origin/master":
$ git branch --unset-upstream

# Create a new tracking connection with the new "origin/main" branch:
$ git branch -u origin/main

Additional Information