main and master: two names for the main branch

main and master are two names for the main branch of a repository, and there is no technical difference between them: both work exactly like any other branch.

master was the default name from the very beginning of git. GitHub switched new repositories to main in October 2020, and git since version 2.28 lets you choose the name of the first branch yourself. Projects created earlier stayed as they were, which is why both names are still around. When you see master in someone else's repository, read it as "the main branch".

One command tells you which one you have:

$ git branch --show-current
main

Set your own default

$ git config --global init.defaultBranch main

The setting applies to new repositories created with git init. It has no effect on a clone: git clone takes the branch name from the server.

Rename it in an existing repository

Locally the name is changed by the ordinary -m flag of git branch:

$ git branch -m master main
$ git branch -vv
* main d01f9d3 [origin/master] first version

The branch is called main already, but it still tracks master on the server. Push it and retarget the tracking:

$ git push -u origin main
To github.com:username/my-project.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Now change the default branch in the repository settings on GitHub: Settings, the General section, the Default branch box. Until you do, the old branch cannot be deleted, because the server still considers it the current one:

$ git push origin --delete master
remote: error: refusing to delete the current branch: refs/heads/master
 ! [remote rejected] master (deletion of the current branch prohibited)

Once the default has moved, the same command goes through:

$ git push origin --delete master
To github.com:username/my-project.git
 - [deleted]         master

For everyone who already cloned the project

Renaming on the server does not touch other people's copies. Anyone who cloned the project earlier still has a local branch called master, tracking a remote branch that is gone. Three commands on their side sort it out:

$ git branch -m master main
$ git fetch origin
$ git branch -u origin/main main
branch 'main' set up to track 'origin/main'.

Warn the team in advance: whoever shows up on Monday and runs git push out of habit gets a puzzling refusal and loses an hour to it.

Common mistakes

Expecting the name to carry special behaviour. It grants no protection and no special permissions: what makes a branch the main one is a setting on the hosting side, while the branch itself stays an ordinary pointer to a commit.

Renaming the branch and forgetting everything that spells the old name out. Build scripts, branch protection rules, deploy configuration and automation jobs often contain master as plain text, and after the rename they quietly stop firing.

Where this is in the book

Chapter 5. Branches: parallel versions of a project.