How to Rename Your Master Branch to Main in Git

How to Rename Your Master Branch to Main in Git

If you're a software developer in 2020, you're likely familiar with the term "master" as the name of the primary branch of development in Git. One recent movement in the tech industry has been around changing the default "master" name to another name like "main".

This move is one that we've adopted at Kapwing, and in this article, we'll discuss some of the thinking that went into this change as well as a short tutorial on how to do it yourself!

What is the current discussion about?

The current discussion has been around naming terminology in software development and how to make it more inclusive to the Black community. The name "master" is significant because it has been both the standard name for the default git development branch but also carries clear references to slavery (e.g. master/slave). In the vein of making technology a more inclusive place, one initiative has been to rename the master branch to a different name. Many names have been suggested, like "primary" and "default", but "main" has so far emerged as the most popular alternative.

Why change Master to Main?

The main argument for changing "master" to "main" is to reduce the occurrences of problematic terminology in a team's codebase. The origin of the term "master" in computing is controversial, but email records from the Git developers confirm that they were referring to the common master/slave metaphor when the industry standard was set. Removing this language from  company vernacular is a small way to help make technology more accessible and inclusive to Black people. "Master" is not the only problematic word; other terms like "blacklist", "whitelist," "black hat", and "white hat", for example, have also been recognized as problematic terminology.

Another argument for changing master to main is to raise awareness in the tech community about micro-aggressions and Black issues. The change is a reminder of the intentionality required to make environments more inclusive.

Why not change Master to Main?

Developers who defend the "Master" terminology argue that it's an engineering standard, and engineering standards are useful and shouldn't be broken without reason. Some say that the change break a lot of code and risks a lot of needless technical headache. Others argue that a different practice could annoy or confuse new developers as they ramp up on a codebase.

Another controversial argument against the change is the idea that the master branch doesn't actually have references to slavery - instead it came from different beginnings similar to words like Master's degree. However, this has since proven to be false based on email records from the development of Git.

Finally, while this isn't an argument against the change per se, there is an argument that changing master to main is simply the work of armchair activists who do the bare minimum in order to sleep easy at night. Some folks claim that changing master to main is just performative allyship - distracting from the real issues, and could allow people to pat themselves on the back for doing something that has very little impact in the grand scheme of the fight for equality.

If you've read through the discussion and have decided to update your master branch name, keep reading for the git commands that we used to do this at Kapwing.

How do I change master to main?

The first thing to do is to "move" or rename the master branch to main.

$ git branch -m master main
$ git status

On branch main

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

nothing to commit, working tree clean

Now in our local repository, we have a main branch that is set to correspond with the upstream master branch. We can try to push the main branch right now, but we'll run into this error:

$ git push
fatal: The upstream branch of your current branch does not match
the name of your current branch.  To push to the upstream branch
on the remote, use

    git push origin HEAD:master

To push to the branch of the same name on the remote, use

    git push origin HEAD

To choose either option permanently, see push.default in 'git help config'.

We've renamed the local branch to main, but the remote branch is still called master. So Git will complain because it doesn't know which branch to push your local branch to. It gives you two options:

  1. git push origin HEAD:master: This will push your local main branch to the existing remote master branch.
  2. git push origin HEAD: This will push your local main branch to the branch of the same name on the remote, in other words, this will create a new branch on the remote called main. This is what we want!
$ git push origin HEAD
Total 0 (delta 0), reused 0 (delta 0)
remote: Create a pull request for 'main' on GitHub by visiting:
remote:      <>
 * [new branch]          HEAD -> main

Now we have two identical branches on our remote repo, master and main. We can navigate to github to check that the branches are indeed correct.

Now you've created a main branch and pushed it to your remote! This is a good intermediate state because you can run your main branch as well as your master branch side by side for a week or so to make sure that there are no issues.

Be sure to update all of your CI pipelines and any other dependencies that might be pointing to the master branch. In our case, we had an auto-deploy configured on Heroku that automatically deployed our app when new commits were pushed to master.

Your deploy pipeline may be different from ours. Because there might be many different services that rely on the master branch, it might be best to run your main and master branches side by side for a few deploys until you feel confident that everything is working smoothly.

When you feel confident that your engineering team is familiar with main and that all pipelines are running on top of main smoothly, the last step is to remove the master branch.

For us at Kapwing, our default branch was already the dev branch, which meant that we didn't have to reconfigure the default. However, if master is your default branch, you may need to first set main to be the default branch before master can be deleted. This is a Github specific setting - in other words, the remote repository usually need a default branch defined in order to know which one to render when you view the repository. There is a good tutorial in this Stack Overflow answer here.

Finally, to delete the master branch: first, checkout the main branch. Then, run git branch -D master. Your output should look something like this:

$ git checkout main 
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

$ git branch -D master
Deleted branch master (was 5aa0c31e6).

Now I've deleted the master branch on my local repo, but I still need to delete the remote master branch. To do that, I can run this command: git push origin :master.

# ericlu @ erics-mbp in ~/sites/kapwing on git:main o [10:47:49] 
$ git push origin :master

remote: error: GH006: Protected branch update failed for refs/heads/master.
remote: error: Cannot delete this protected branch
 ! [remote rejected]     master (protected branch hook declined)
error: failed to push some refs to '[email protected]:kapwing/kapwing.git'

Oh no! Like many organizations, we've set our master branch to be protected. In other words, it's not possible to delete the branch from the remote repository without special access.

However, running this command would work for you in many non-protected scenarios. Just make sure that you are completely sure that you are ready to delete master!

In Github, I can delete protected branches in Settings → Branches. I will use this UI to delete our master branch.

Now I can rerun my command, and the remote deletion is successful:

$ git push origin :master

 - [deleted]             master

There you have it! Now our main repo at Kapwing operates without a master branch.

Cleanup: For some configurations, you might find that the local main branch is still pointing at a master branch that no longer exists.

$ git status
On branch main
Your branch is based on 'origin/master', but the upstream is gone.
  (use "git branch --unset-upstream" to fixup)

nothing to commit, working tree clean

Git is saying that the current local main branch still corresponds to the deleted remote master branch. This can be fixed by unsetting the "upstream" branch, which is another name for the remote branch.

$ git branch --unset-upstream
$ git status
On branch main
nothing to commit, working tree clean
$ git push
fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin main

$ git push --set-upstream origin main
Branch 'main' set up to track remote branch 'main' from 'origin'.
Everything up-to-date

The unset-upstream command will remove the remote branch, but then you have to set the upstream to the correct main branch. Just run git push --set-upstream origin main and everything will be all set!

Why did we change master to main at Kapwing?

While every company needs to make their own informed decision, at Kapwing we decided to change our master branch to main.

We want to work to reduce any racially charged terms in our codebase, whether they are broadly offensive or not. We want to be as inclusive as possible, and that means taking steps to eliminate problematic terminology.

It's likely true that changing the name of a branch in our company is not necessarily going to make a large direct impact Black people and Black issues in America today. However, changing the name does help raise awareness for Black people in tech. We feel that it is right to take any step we can towards a more inclusive environment, and it's a no brainer when the step is as small as changing a branch name.

However, we also are staying mindful of the fact that the fight for equality doesn't end with changing master to main. We can't pat ourselves on the back for solving racism just because we made such a small change. On the contrary, there's a much longer way to help achieve equality, both in the tech community and beyond. We've taken action in other ways too, starting with donating our Youtube revenue to Black content creators, as well as taking time to educate ourselves as a team on Black issues in the US today. But we are aware that these are only very small steps in the right direction.


We feel that as members of the tech community that we're responsible for thinking of creative ways that we can contribute to the Black Lives Matter cause. We've supported our employees who have participated in protests, published content about how to use our product to support the cause, spotlighted amazing black creators in our community, donated to the Equal Justice Institute, and publicly expressed our position. We recognize that there's a lot of progress yet to come to make the tech startup world more equitable, but we saw changing Master to Main as one step we could take to eliminate bias in our codebase. We hope this article helps you understand the issue more and that you might take action to do the same on your team!

Create content faster with Kapwing's online video editor →