How to track remote branches in Git

Greg Foster
Greg Foster
Graphite software engineer

A remote branch in Git represents a branch on a remote repository (hosted on services like GitHub, GitLab, etc.). It acts as a pointer to the state of the branches on your remote servers. The name of a remote branch typically has the format <remote> <branch>, for example, origin/main. These branches are crucial for collaborating with others, allowing you to see and interact with changes pushed by others before integrating them into your local branches.

This guide explores what remote branches are and how to track them using various Git commands.

Tracking a remote branch means configuring a local branch to automatically "track" changes from a specified branch in a remote repository. This is necessary for Git operations like pulling new changes and pushing your commits.

The first step in tracking remote branches is fetching all of the existing remote branches from the remote repository.

To fetch all of the remote branches that currently exist on the remote, but may or may not exist on your local machine, run:

git fetch --all

This command will fetch the metadata for all of the remote branches in the repository. You can then point specific local branches at any of the fetched remote branches.

To create a local branch that tracks a remote branch, use the git checkout command. This operation automatically sets up the local branch to track the remote branch if the branch doesn't exist locally:

git checkout -b <branch-name> origin/<branch-name>

This command does two things: it creates a new branch <branch-name> in your local repo and sets it to track the remote branch origin/<branch-name>.

If you prefer to explicitly set up a local branch to track a remote branch, you can use:

git branch --track <local-branch-name> origin/<remote-branch-name>

And then checkout the branch:

git checkout <local-branch-name>

You can combine creating a new branch and setting up tracking in one step with:

git checkout -b <local-branch-name> --track origin/<remote-branch-name>

This command not only checks out your local state to the new branch but also sets up tracking with the specified remote branch.

To change the remote branch that your local branch tracks, use the following command:

git branch -u origin/<new-remote-branch> <local-branch-name>

This is useful if you initially tracked the wrong branch or if the tracked branch has been deleted.

Sometimes, you may want to create a new local branch and have it track a remote branch from a different remote (not the default origin). To do this, run:

git checkout -b <local-branch-name> <different-remote>/<remote-branch-name>
git branch --set-upstream-to=<different-remote>/<remote-branch-name> <local-branch-name>

If you want to checkout a remote branch for a quick look without setting up tracking, use:

git checkout --no-track -b <local-branch-name> origin/<remote-branch-name>

This creates a new local branch based on the remote branch but without setting up tracking, allowing you to keep your currently tracked branch while still being able to investigate the remote.

If you have an existing local branch and decide later to set it to track a remote branch, use:

git branch --set-upstream-to=origin/<remote-branch-name> <local-branch-name>

This command adds tracking information to your already existing local branch.

For further information on tracking remote branches in Git, see the official Git documentation.

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