How to track remote branches 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.


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:

Terminal
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:

Terminal
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:

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

And then checkout the branch:

Terminal
git checkout <local-branch-name>

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

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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.

Git gud
"It's the first Git workflow I've used that actually feels good."
–@robboclancy
Learn more

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