master vs main

Femi Adisa
4 min readApr 15, 2021

I just started working on my Phase 4 project in the Flatiron School program and was welcomed with a dilemma.

Wait a min; why do I have two base branches? I see a notification to “compare and pull changes” from master to main, but even though main only has a Readme while the master branch has a brand new rails app, when I click on the green “pull” button, it tells me “there isn’t anything to compare” because “main and master are entirely different commit histories”, which then starts to make sense.

Well, I knew the master branch used to be the main (of course, I could easily make the master branch the default by going to the repo Settings->Branches-> changing the default branch to master, but that doesn’t take care of the other branch, and something about my coding experience makes me feel uncomfortable with code bloats (or any kind of bloats, really)

mmm.. no bloats; source: giphy

common causes of master and main in a git repo

Little backstory here: starting from “Oct. 1, 2020, any new repositories you create will use main as the default branch, instead of master," according to GitHub. This is one of other steps taken by many organizations to abandon non-inclusive terms that reference slavery

The most common cause of having both main and master branches is because a master branch is pushed into a repo with main as the default branch. This can be due to a lot of reasons. In my case, I initialized my git repo with a README and then set the remote of a new rails project to that repo. Some versions of rails still initialize new apps with master as the default branch, as did mine. So when I git push-ed to the repo, it created a remote master branch that the local branch would track.

use cases

since the ideal flow in github version control is to create new branches for testing and then merging back to the main/master when it is proven that the added code won’t break anything, I don’t think there would be a reason to have two main branches, but if your situation calls for it and, depending on the size of your project, you can manage the complexity that arises from doing so, then there isn’t really anything stopping you from using both.

how to change master to main

there are a lot of resources available on github itself and other sites about this, but it is pretty easy.

If you have a new project and haven’t made any push(es), you can

1. git branch -m master main //this changes the local branch from master to main; if you are on the master branch, you can omit the master 
2. git add <files/directory>
3. git commit -m <commit_comments>
4. git push -u origin
//origin or whatever name you’ve given to your remote

If you only have master but want to change to main, you can

1. /* rename your remote branch on github */
2. /* rename the local branch using */ git branch -m master main
3. git fetch origin
4. git branch -u origin/main main

Finally, if you have a master and a main and want to switch to main only, you can merge with the main branch. Since the contents of master is the working code, you should be able to “merge” this code into your main directly; if it doesn’t work due to an “unrelated history” error, you can add a — allow-unrelated-histories tag. This step can be done in two ways:

  1. rename the current branch from master to main, change it’s remote to main, pull down/merge from main, and then push up (this is suitable when there’s nothing important in the main yet)


2. create a new local branch called main, set it to track the remote main, pull in the local changes from master (ie merge), (pull down the remote main and resolve conflicts), and then push up

Step 1 code along:

git branch -m master main //renames master to main
git fetch origin //gets the latest commit from the remote
git branch -u origin/main main //makes the local main branch track the remote main branch
git remote set-head origin -a //
git merge origin main --allow-unrelated-history //will allow you to merge the current branch with the remote main branch, and then you’ll be able to push up using normal git push
git push origin --delete master //deletes the unneeded remote master branch

Step 2 code along:

git checkout -b main //creates a new branch main and switches to it NOTE: by default, git checkout -b bases the new branch off the current HEAD; if you change that, make sure your work is in the new branch before deleting the local master 
git branch --set-upstream-to=origin/main main //sets the newly created main branch to track the remote main branch
git branch -d master //deletes the local master branch
git push origin :master //updates the remote repo to delete the remote master branch
//if you try pushing but get a "unrelated histories" error, try
git pull origin main --allow-unrelated-histories //fix any conflicts that occur
//then you should be able to push without any problems

questions? google ‘em

feedback? drop a comment!