If you are tired of typing master by habit and getting judged by future you then this guide will make main the default branch for new repos and help you rename existing ones with minimal chaos. It keeps the Git commands simple and the explanations sarcastic but accurate.

Prepare new repositories

Make sure every new repository you create starts with main so you never have to rename things again. Run this once on any machine where you init repos.

git config --global init.defaultBranch main

Now git init will create main instead of master. Yes this is boring but worth it.

Rename an existing repository locally

If you already have a repo that uses master do this inside the repo. It renames your local branch and keeps your working tree intact.

git checkout master
git branch -m master main

If you had uncommitted changes they will still be there. Git does not care about your feelings.

Push the new branch and update the remote

Tell the remote about the new branch name and set upstream so future pushes go to the right place.

git push -u origin main
# optional remove old remote branch once hosting default is switched
git push origin --delete master

Do not delete the remote master until your hosting platform is configured to use main as the default. Otherwise pull requests and default protections will get cranky.

Update the default branch on your hosting platform

Go to your project settings on GitHub GitLab or Bitbucket and switch the default branch to main. Or use the hosting API if you enjoy scripting away your free time. Changing the default keeps new pull requests and protections targeting the right branch.

Quick checklist for hosting

• Change the default branch in repository settings
• Move branch protections and required checks to main
• Make sure CI and deployment pipelines expect main

Update references and continuous integration

Search for hard coded references to master and update them. These can hide in CI configs scripts and documentation. Use git grep and a bit of sed or your favorite editor to fix them.

git grep -n "master"
# edit files that mention master and replace with main

Remember to run your tests on main before you delete the old branch from the remote. Automated checks will thank you in fewer error emails.

Automate multiple repositories

If you have many repositories do not rename each by hand unless you really enjoy repetitive strain. Here is a basic bash loop to get you started. Adapt it for your hosting API to change defaults remotely.

for repo in git@example.com:org/repo1.git git@example.com:org/repo2.git; do
  git clone "$repo"
  dir=$(basename "$repo" .git)
  cd "$dir" || continue
  git checkout master || git checkout -b master
  git branch -m master main
  git push -u origin main
  cd ..
done

Wrap up

You have now made main the default for new repos renamed existing branches pushed the changes and learned to update hosting settings and CI. It is not glamorous but it is effective. If you manage many repositories consider adding the hosting API to the script and run tests against main before declaring victory.

Final tip Keep backups and do this during a calm workday rather than during a production frenzy. Your future self will send you a thank you note or at least fewer angry Slack messages.