Git checkout main

Greg Foster
Greg Foster
Graphite software engineer

In Git, the checkout command is used to switch between branches in your repository.

This guide will explain how to use the git checkout command specifically to switch to the main branch, update it, and handle common tasks related to this branch.

Although the industry has been shifting towards using the term "main" for the default branch, "master" is still sometimes used in many existing repositories. For the purposes of this guide, we'll be exclusively using main. If your repository is still using the deprecated naming convention of master simply substitute master for main in all of the following commands.

The git checkout command is used to switch branches or restore working tree files. It updates the files in the working directory to match the version stored in that branch, and it updates the Git's HEAD (the pointer to the commit at the tip of a branch) to point to the specified branch.

To switch to the main branch in your local repository run:

Terminal
git checkout main

This command will switch the current working directory to the main branch, updating the working directory to reflect the state of the specified default branch.

If you're working with remote repositories (often named "origin"), you might need to check out the main branch as tracked on the remote. Before checking out, you should ensure that your list of branches is up-to-date:

Terminal
git fetch origin

Then, to switch to the main branch exactly as it is on the remote repository:

Terminal
git checkout origin/main

This command checks out the main branch from the origin remote into a detached HEAD state in your local repository, meaning any commits you make will not be on any branch and can be lost if not handled correctly. It’s mainly useful for inspecting the remote branch or for temporary experiments.

If you are working directly on the main or main branch and there are updates on the remote, you may want to update your local main branch:

Terminal
git checkout main
git pull origin main

This sequence of commands first switches to the main branch, then pulls the latest changes from the main branch of the origin remote, merging them into your local main branch.

Often, you might switch to the main branch and immediately need to update it to ensure it's up-to-date with the remote repository:

Terminal
git checkout main
git pull

This is a straightforward way to both switch to the main branch and fetch and merge the latest changes from the upstream branch.

  • git checkout main not working: This could occur if the main branch does not exist locally. Make sure you have the main branch by listing all branches with git branch -a. If it's missing, you may need to fetch from the remote and then try checking out again.

  • Detached HEAD state: If you find yourself in a detached HEAD state after checking out origin/main, you can return to the main branch and merge your changes:

    Terminal
    git checkout main
    git merge origin/main

    This will restore your local state to track the mainline of the branch, putting you back into lockstep with the history of the repository.

  • Branch not up to date: If git pull does not update your branch as expected, ensure that your local branch tracks the appropriate remote branch. Check the tracking relationship using git branch -vv and set it with:

    Terminal
    git branch --set-upstream-to=origin/main main

For further reading see the official Git documentation on branch management.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2