Renaming the default branch in Git from master to main is easy. Let’s look at two scenarios: changing a local repository, and changing a repository on GitHub.

A local repository

Let’s transition a local repository that isn’t pushed anywhere. Maybe this repo is for a personal pet project, or maybe it’s an experiment that we did quickly. Let’s replace the master branch to main.

Open a terminal in the repository and let’s get the current log:

git log --oneline --graph --decorate --all

We can see the master branch, and HEAD is pointing to this branch.

1. Create the new branch:

   git checkout -b main

   This creates the new branch and checks it out at the same time.

2. Delete the old branch:

   git branch -d master

We can verify the change is made successfully:

git log --oneline --graph --decorate --all

Why would we make this change?

After all, no one will notice. Well, you’ll notice. Is your goal to make a change or to make a statement?

Change default branch on GitHub

Let’s transition a repository that’s shared among our team. The default branch is the one shown when we first load GitHub, the README.md is shown below our code. When we clone the repository, this is the branch we’ll first have checked out. Let’s change it from master to main.

Open a terminal in the repository and let’s get the current log:

git log --oneline --graph --decorate --all

We can see the master branch, and HEAD is pointing to this branch. We can also see origin/master, the reference on GitHub.

1. Create the new branch:

   git checkout -b main

   This creates the new branch and checks it out at the same time.

2. Push this branch to the server:

   git push origin main

   This gets the branch up on GitHub, but doesn’t yet make it the default.

3. Change the default branch:

   On GitHub, select settings, branches, and in the drop-down pick main.

   Click OK to the warning. This warning helps us understand that we’ll close any open pull requests against master and potentially affect any cloned or forked repositories.

4. Delete the old branch locally:

   Back in the terminal:

   git branch -d master

   If it complains that the branch is not fully merged, you may need to merge master into main first: git checkout main; git merge master; git branch -d master;

5. Remove the old branch from the server:

   git push origin :master

   The : is the magic sauce that removes the branch from the server.

Verify the change by refreshing the main repository page on GitHub and noting that main loaded by default, and that master is nowhere to be found. Good.

Verify the change locally by running git log --oneline --graph --decorate --all and also verifying master is gone.

FAQ:

What about my co-workers?

We’ve already changed the server, so they won’t need to do that. But they will need to change their own repository.

1. Get the latest:

   git pull

   If you’re on the master branch when you do, you may get an error, so instead:

   git fetch origin

2. If you’re currently on master, switch to the new branch:

   git checkout main

   If you’re on any other branch such as develop or a feature branch, skip this step.

3. Remove the old branch:

   git branch -d master

4. Remove the old reference:

   git remote prune origin

   This says roughly “go delete all my local pointers to the remote branches that no longer exist.”

What about forked repositories?

If you began this repository by forking another GitHub repo, you can make this change on your copy, but you’ll need to petition the maintainers to make this change on the main repository. Sadly, there’s no way to create a pull request to change the default branch.

What if my default branch isn’t master?

If you’re using GitFlow or GitHub Flow or another branch naming strategy, your default branch may be develop or dev or similar. You likely still need to create main and remove master, but you don’t need to change the default branch. You may consider naming it prod instead of main. You need only skip step 3 above.

What about my DevOps pipeline?

If you have automation around branch names, you may need to change Jenkins or GitHub Actions to tell the build that it should look to main rather than master.

Can I make this the default for new repos?

There are some kludgy workarounds for getting Git to automatically create the main branch instead of the master branch, but they’re awkward at best and not durable to Git version upgrades. Sadly, it’s best if you repeat this procedure each time you create a new repo … for now.

Are they changing Git to do this by default?

Yes. in both https://lore.kernel.org/git/CAOAHyQwyXC1Z3v7BZAC+Bq6JBaM7FvBenA-1fcqeDV==apdWDg@mail.gmail.com/ and https://github.com/git-for-windows/git/issues/2674, official maintainers of Git are working to find a new name and incorporate it into the culture of the product. GitHub is also working on it says Nat Friedman.

Can I ask more questions?

Most definitely. Hit me up on twitter: @rob_rich or send me an email.