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!
Table of Contents
- This tutorial uses version 2.30 of Git SCM (source code management) on Windows 10 but will work on any Git-supported OS.
- A remote Git repository such as GitLab, GitHub, or Azure DevOps. In this article, repositories are provided to learn from, or you may use your own.
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
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.
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.
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>
4. Navigate to the cloned repository with the command,
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.
For most modern Git software,
mainis the default primary branch. You may encounter an older application that uses
masterfor their default branch name, but both names are functionally the same. This tutorial uses branches named
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,
Two additional tracked remote repositories are named
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
You may wonder why the separate URI’s for
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.
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.
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.
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
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,
# 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
Any time you check for remote updates with
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
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
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
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
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
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
Future versions of Git may possibly prefer that you use the
git switchcommand for changing and creating branches. The Git
switchcommand 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, 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,
# 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
HEADis 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
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
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: