Renaming the default branch in Git

I like the idea of renaming the Git “master” default branch. In my personal project repositories, none of the definitions of the word “master” make sense for what I do with the branch.

Just in case you want to do the same before your repository server has an option to do it for you, here are the steps. In this case, I’m renaming master to main.

1. Browse to your local copy of the repository to start, and make sure you don’t have any local changes. Local changes are any files you modified, added, or deleted without having sent the changes to the remote yet. (You usually have local changes if you are working on stuff in that repository at the time.)

   Commit, stash, reset or delete the local changes depending on how much you want to keep the local changes.

2. Now that the local changes are out of the way, sync up to the remote copy of the master branch you are renaming.

   git checkout master
   git pull
   

3. Create the branch with the new name. In this case, main,

   git branch main
   git push --set-upstream origin main
   

4. Switch your local repository copy to the new main branch

   git checkout main
   

5. Verify all your tooling can use that main branch or is aware of the default Git branch without using its name before continuing. Tools you may need to reconfigure are:

   • Hooks
   • Continuous integration builds
6. Change the default branch on the server side. This is different depening on the repository.
   • Github
   • Gitlab
   • Bitbucket

7. Finally, delete the old default branch on the server side:

   git push --delete origin master
   

8. View the repository in the server’s web interface or clone a new copy from the server. You should no longer see the old default branch.

9. Delete your local copy of the old default branch (so that you don’t accidentally push and recreate it).

   git branch -d master