How to Check out a Remote Git Branch [Step-by-Step]

Devin Rich

Read more posts by this author.

Have you been newly onboarded to a team and told to checkout a remote branch of the Git code repository? Used by teams large and small, remote Git branches unlock powerful code collaboration abilities. In this article, learn and understand how to retrieve the code from a remote Git repository!

Prerequisites

Other potential installation methods for Windows are Chocolatey and Git4Win.

What is a Remote Branch?

Git repositories store and track a series of related commits in a branch. By default, a commit automatically lives in the currently assigned branch, typically main or master.

A remote branch is a branch that exists on a remote Git repository. These remote repositories, referred to as “remotes,” are where your local Git repository will look for external commit updates once configured.

Find out what branches are available with the Git branch command. The starred (*) branch is the currently active branch. The branches shown below are only local branches as no remote branches exist yet.

git branch
List of local branches shown from the git branch command.
List of local branches shown from the git branch command.

What is Git Checkout Remote Branch?

Say you have a local Git repository and need to start collaborating with others. To do that, leverage the Git checkout command to retrieve the latest commits from a remote branch on a remote Git repository.

With a configured remote branch, Git will instead mirror a remote branch instead of a local-only branch. An example of the command git checkout remote <branch> is shown below.

git checkout remote main

Clone the Remote Git Repository

As an existing repository exists, you are ready to get started. Follow along below to clone the remote repository to a local folder.

1. Cloning a remote repository may be easiest via the HTTPS URL rather than SSH to avoid certificate and firewall issues.

  • Navigate to the repository in GitHub.
  • Click the Code button and select HTTPS.
  • Click the Clipboard icon next to the link to copy the URL to the clipboard.
Locating the HTTPS clone URL in GitHub.
Locating the HTTPS clone URL in GitHub.

2. Once you’ve copied the HTTPS URL to your clipboard, open a command-line using your favorite CLI, such as Windows Command Prompt or the Windows Terminal.

3. Navigate to a folder where you want the cloned the repository to reside. This tutorial uses the git folder in the home directory as you will see in the screenshots. Run the following command to clone the repository, which creates a sub-folder containing the remote repository.

# GitHub git clone <https://github.com/Adam-the-Automator/git-checkout-remote-branch>
Cloning a remote repository to the local machine.
Cloning a remote repository to the local machine.

4. Navigate to the cloned repository with the command, cd git-checkout-remote-branch.

Run the following status command to verify that the repository has been successfully created. The Git status command displays differences between the local branch and remote branch, useful to determine if your branch is connected and up to date! The default Git remote is named origin as prefixed to the main remote branch. git status

git status
Checking a repositories status.
Checking a repositories status.

For most modern Git software, main is the default primary branch. You may encounter an older application that uses master for their default branch name, but both names are functionally the same. This tutorial uses branches named main, RemoteBranch, SomeBranch, and AnotherBranch.

What is a Git Remote and How to Track Branches

Cloning a repository automatically creates a reference to a remote source, known as a remote. This reference is used to check for new commits or push new changes to the remote repository.

A Git repository itself may have multiple remotes, but a branch can only reference a single remote.

Tracking a remote branch creates a relationship to a local branch. This relationship allows you to easily push or pull commits the remote branch to the local branch. In addition, a tracked branch determines how far ahead or behind in commits the local branch is from the remote.

Listing a Git Repositories Remotes

First up, check to see if the repo you’re working with has any Git remotes. To do that, view Git remotes in your repository with the git remote command as shown below. In this example, two remotes are shown, origin and remote2.

git remote
Viewing a repositories two configured remotes.
Viewing a repositories two configured remotes.

Two additional tracked remote repositories are named origin and remote2, where your remotes may be different.

To see more detail about the configured remotes, add the v switch to display the full Git remote URI.

git remote -v
Viewing verbose details about repo remotes.
Viewing verbose details about repo remotes.

You may wonder why the separate URI’s for fetch and push. Some Git workflows allow you to check for updates to a repository at a different URI than where you may send changes, this is called the triangular workflow.

Viewing Available Remote Branches

Display all available branches, both local and remote, in your repository with the branch command. To show the remote branches as well, append the all switch, as shown below.

git branch --all

In the below screenshot, you can see that the remote repository origin that the tutorial is using is shown as expected. However, this screenshot is missing all branches from the remote named Remote2.

Viewing all known branches in a repo (including remotes).
Viewing all known branches in a repo (including remotes).

If you know that a branch is on your remote, but it isn’t showing on the branch list, you must update your list of available remote branches as covered in the next section.

Updating the Available Remote Branches

Sometimes a remote repository may add or change branches. To make sure you are working with the most up to date branches, you may need to run the git fetch command.

The fetch command will connect to the remote repository and retrieve a list of all available branches. View your currently tracked branches after running the git fetch command to see that the remote branch is now visible, as demonstrated below.

# Retrieve available remote branches
git fetch

# Verify that all branches are now available on the local Git repository
git branch --all

You can see below that the branch remotes/origin/RemoteBranch is now showing in the list of available remote branches.

Using git fetch to update the list of available remote branches.
Using git fetch to update the list of available remote branches.

Fetch itself only checks for updates from the remote that is currently tracked in the current branch. To have Git check for updates from all remotes in the repo, regardless of tracking status, add the all parameter.

git fetch --all

To fetch the available branches from a specific remote, add the remote name to the git fetch command, Remote2 in the example below which retrieves the branch, main.

# List available branches in a local Git repository
git branch --all
# Fetch available branches from remote2
git fetch Remote2
# Verify that the remote2 branch, main, is now available
git branch --all
Fetching mainfrom remote2 with the git fetch command.
Fetching mainfrom remote2 with the git fetch command.

Any time you check for remote updates with git fetch, git pull, or git push, Git will compare commits with the remote branch. Local branches can track any Git remote branch. In addition, multiple local branches can be set to track the same remote branch.

Viewing Each Branch’s Remote Tracking

To see the tracked remote branch and corresponding local branch, use the vv parameter with the command git branch. The command results are a list of remotes and branches in the format [<remote>/<branch>] as shown below.

git branch -vv
Listing remote tracking of all local branches.
Listing remote tracking of all local branches.

Changing a Branch’s Remote Tracking

You may need to change your local branch to track a different remote branch. To set your current branch to a specific remote branch, track the remote branch with the u parameter, as shown below.

git branch -u Remote2/main
Setting what remote to track for the current branch.
Setting what remote to track for the current branch.

Checking out Git Remote Branches

With newly created branches on the remote Git repository, you may need to checkout a different branch. Checking out a remote repository branch is done through the checkout command.

If the following conditions are met, Git will automatically determine the right remote, download a local copy of the remote branch, and set the local copy to track against the remote branch. Verify the following conditions are not met through the results of git branch --all command.

  • A local branch with the same name does not already exist.
  • Multiple remotes that use the same remote branch name do not exist.

To perform the checkout, use the git checkout command and type the name of the remote branch as seen below.

git checkout RemoteBranch
Creating a local branch from a remote branch with git checkout.
Creating a local branch from a remote branch with git checkout.

If your local repository already contains a local branch with the same name, add the b parameter to specify an alternate local branch name before the remote branch to checkout.

git checkout -b AnotherBranch origin/RemoteBranch
Creating a local copy of a remote branch with an alternate local branch name.
Creating a local copy of a remote branch with an alternate local branch name.

If your local repository has multiple remotes with the same branch name, specify which remote and branch to track local commits against.

git checkout --track origin/RemoteBranch
Creating a local copy of a remote branch with tracking enabled.
Creating a local copy of a remote branch with tracking enabled.

Future versions of Git may possibly prefer that you use the git switch command for changing and creating branches. The Git switch command is only for branches while the Git checkout command has many abilities. Irshad S. wrote a nice primer on the rationale if you’d like to read more about it.

How to Push a Local Branch to a Remote

If you create a local branch that doesn’t have any remote branch for tracking, you can push the branch to the remote via the git push command. The simplest method to create a new branch on your desired remote is with the u parameter.

The u parameter, as you used above, requires the arguments of the repository name and the source branch. By only specifying HEAD as the source branch name, Git knows to use the current local branch name as the name on the remote, in this case, NewBranch.

# Checkout and switch to NewBranch
git checkout -b NewBranch
# Create NewBranch on the origin remote
git push -u origin HEAD
# Verify that the branches on the remote now exist
git branch -vv
Pushing a local branch to a upstream remote named origin with the same name as local.
Pushing a local branch to a upstream remote named origin with the same name as local.

HEAD is a shortcut that simply means the current branch. You can push other branches to the remote and establish tracking by using their name instead of HEAD.

There are times when the current local branch does not match the remote branch’s name. To use a different name, specify the desired branch name after the source is joined by a colon, as seen below.

# Create the current branch on the origin remote as AnotherBranch
git push -u origin HEAD:AnotherBranch
# Verify that the local NewBranch now exists as AnotherBranch on the origin remote
git branch -vv
Pushing a local branch to a upstream remote named origin with an alternate remote branch name.
Pushing a local branch to a upstream remote named origin with an alternate remote branch name.

Next Steps and Additional Resources

You’ve now reviewed the basics of Git, how to manage remotes, and how to track remote branches. You’ve also learned several ways that you can check out a remote branch and some best practices when using Git. This knowledge will help save you from frustration in the future.

If you need to read up on some other aspects of managing a Git repository, be sure to check out these good Git resources that are available:

  • A primer on detached heads: When you accidentally get your HEAD detached and when you’d actually want it that way.
  • Git switch: Only for dealing with branches, unlike Git checkout.

Looks like you're offline!