How to rename the master branch to main in Git?

In this article we will learn how to rename the name of the branch.

In this brief write-up, you will discover a guide on how to change the default branch name "master" to "main" (or any other preferred term) in your Git repositories, tailored to meet your team's specific needs.

Renaming the local master Branch to main

Like any other steps the first steps is to rename the master branch in your local Git repositories:

$ git branch -m master main

Let's check if we renamed the branch in local as expected.

$ git status

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

nothing to commit, working tree clean

Great progress has been made! The local branch has been successfully renamed, but now we must also modify the remote repository to reflect these changes.

Renaming the remote master Branch to main

During the second step, we will need to create a fresh branch on the remote repository with the name "main" since Git doesn't permit directly renaming a remote branch. To achieve this, we'll establish a new "main" branch and then remove the existing "master" branch.

Before executing the following command, ensure that your present local HEAD branch is still "main."

$ git push -u origin main

Now that we have created a new branch on the remote repository with the name "main," let's proceed to eliminate the old branch named "master" from the remote repository:

$ git push origin --delete master

Based on your specific configuration, this process might have been successful, and the branch renaming accomplished. However, in numerous instances, you may encounter an error message similar to the following:

To https://github.com/Pratap22/learn-grpc.git
! [remote rejected]   master (refusing to delete the current branch: refs/heads/master)
error: failed to push some refs to 'https://git@github.com/Pratap22/learn-grpc.git'

Similar to other code-hosting platforms, GitHub requires the definition of a "default" branch, and deleting it is not permitted. Moreover, your previous "master" branch could be designated as "protected." Therefore, before proceeding, you must resolve this issue. Here's how to do it in GitHub:

Now that you have resolved the issues with the default branch and protected status, you can try deleting the "master" branch again from the remote repository, which should now be successful.

$ git push origin --delete master
To https://github.com/Pratap22/learn-grpc.git
 - [deleted]           master

Conclusion

In conclusion, renaming the "master" branch to "main" (or any other preferred name) in Git repositories involves creating a new branch on the remote repository, setting it as the default branch, and deleting the old "master" branch. However, certain platforms, like GitHub, have additional requirements, such as a protected "master" branch or a default branch designation, that must be addressed before the renaming can be completed successfully.

Learn More

1. Getting Started with Git - A beginner's guide
2. How to Delete a Git Branch Both Locally and Remotely?
3. Some useful Git commands that may save your life

Please let me know if there's anything else I can add or if there's any way to improve the post. Also, leave a comment if you have any feedback or suggestions.