How to change the default branch in Git

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


The default branch in Git is the primary base of development and is typically the branch where all changes eventually merge back. This is also the branch that Git automatically checks out when you clone a repository. Originally, Git designated 'master' as the default branch name, but recent conventions and best practices encourage using alternative names like 'main'.

  1. Create the New Branch (if it does not exist): As an example, let's change the default branch from "master", the outdated convention, to "main", the current naming standard.

    If the new default branch does not exist, first you need to create it. This is typically done by branching off from the old default branch:

    Terminal
    git checkout master
    git checkout -b main
  2. Push the new branch to remote:

    Push the new branch to your remote repository:

    Terminal
    git push -u origin main
  3. Change local default branch:

    To change the default branch locally, you use the git symbolic-ref command:

    Terminal
    git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

    This command sets the HEAD of your local clone to point to 'main' instead of 'master'.

For repositories hosted on GitHub, you need to update the default branch through the web interface.

  1. Navigate to the Repository Settings:

    • Go to your repository on GitHub.
    • Navigate to the "Settings" page at https://github.com/<ORG_NAME>/<REPO_NAME>/settings.
  2. Change the default branch:

    • In the "Default branch" section, click the switch button next to the current default branch.
    • Select the new default branch from the dropdown and confirm the change.

    Screenshot of default branch

    Changing the default branch on GitHub automatically updates new clones and existing checkouts to point to the new default branch.

  3. Delete the old branch (optional):

    After ensuring all pull requests and changes are merged into the new default branch, you can choose to delete the old default branch:

    Terminal
    git push origin --delete master

If your repository is hosted on platforms other than GitHub, like GitLab or Bitbucket, the process to change the default branch is similar but accessed through their respective settings:

  • GitLab: Go to "Repository" > "Settings" > "Repository" and change the default branch under "Default Branch".
  • Bitbucket: Navigate to "Repository settings" > "Branches" and change the default branch under "Main branch".

Once the default branch is changed remotely, team members should update their local repositories to reflect this change:

Terminal
git fetch origin
git branch -u origin/main main
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

These commands adjust the local configuration to track the new default branch and ensure that the HEAD is correctly set.

For more information on default branches see the official documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2