Git checkout remote branch PROPERLY [5 methods]

Git checkout remote branch

Git Checkout remote branch is the ability for several programmers collaborating on a project to access each other’s codes during the project. It is simply the act of navigating a remote branch.

Git is an open-source that allows several software developers to keep track of any modifications occurring in their codes on a collaborated project. Separately, git will store all the previous versions before the changes in a specific database. Git allows different programmers to work concurrently on the same code without interfering with each other’s output. The git checkout remote branch function allows a single developer to work alone and still collaborate with the rest on a project.

In this tutorial, we are going to cover how the git checkout remote branch works, the scenarios in git, benefits, and its best practices when contributing to a project.

Workflow for git checkout remote branch

The basic workflow to checkout remote branch would be following steps.

## Fetch all the remote branches which were not yet setup to track on our local machine
git fetch

## List remote branches
git branch -r

## Checkout your remote branch
git checkout remote_branch

But depending upon environment, the git version used you may face different issues. Hence I have consolidated different commands and methods you can use to perform git checkout remote branch.

Pre-requisite: Clone your repository

I have set up my project git_examples on GitLab which I will be using to demonstrate this article. I have already cloned my project’s main/master branch into my local workstation.

My local workstation is running on windows 10 pro. Before starting I will clone the git_examples project using the syntax below. When starting from scratch always clone your repository to have it in your local workstation. It doesn't matter which branch you use to clone the repo as we will share the steps to checkout different branches from the remote repository.

$ git clone git@gitlab.com:golinuxcloud/git_examples.git

Sample Output:

Method-1: Fetch your repository and checkout remote branch

After cloning your repository, a plain git fetch without arguments will update all the remote-tracking branches. By applying the git fetch –all command, you will be able to fetch all the modifications made to the remote repository and place them into your local repo.

You can use the following syntax to initiate the git fetch and checkout remote branch:

$ git fetch origin <remote_branch>:<local_branch_name>

In my setup I have the following branch available on local and remote:

Here, we will checkout new-feature remote branch with git fetch:

deepak@ubuntu:~/git_examples$ git fetch origin new-feature:new-feature
From gitlab.com:golinuxcloud/git_examples
* [new branch] new-feature -> new-feature

So, git fetch has created a new branch and mapped it to the provided remote branch.

deepak@ubuntu:~/git_examples$ git branch -a
main
new-feature
* new-issue-7843
remotes/origin/HEAD -> origin/main
remotes/origin/main
remotes/origin/new-feature
remotes/origin/new-issue-7843

But currently we are not active in this new-feature branch so you can either use git checkout or git switch based on your git version to change your active branch:

deepak@ubuntu:~/git_examples$ git switch new-feature
Switched to branch 'new-feature'

Method-2: git checkout remote branch

Fetch all the remote branch information to your local workstation

$ git fetch

Let us list the available remote branches on our local workstation using git branch -r:

Next you can use following syntax to checkout a remote branch by providing the name of the respective remote branch from above output:

$ git checkout origin/<remote_branch>

The git checkout branch command creates a local copy which you will now use to edit your codes on a shared project.

deepak@ubuntu:~/git_examples$ git checkout new-issue-7843
Branch 'new-issue-7843' set up to track remote branch 'new-issue-7843' from 'origin'.
Switched to a new branch 'new-issue-7843'

From the above example, you have switched from the main/master branch to remote branch new-issue-7843

Method-3: Checkout remote branch using the same branch name

We already highlighted this command usage in Method-2 above. You can execute the following command to checkout remote branch

$ git checkout -b <remote_branch_created_on_local> origin/<remote branch>

It is possible while executing this command you may get the following error:

fatal: git checkout: updating paths is incompatible with switching branches.
Did you intend to checkout 'origin/remote_branch' which can not be resolved as commit?

This is most likely because you have not performed a git fetch operation. So to overcome this you must fetch all the remote branch details.

First perform git fetch:

deepak@ubuntu:~/git_examples$ git fetch

Next list the available local and remote branch:

Assuming we want to checkout new-feature remote branch, we will use:

deepak@ubuntu:~/git_examples$ git checkout -b new-feature origin/new-feature
Branch 'new-feature' set up to track remote branch 'new-feature' from 'origin'.
Switched to a new branch 'new-feature'

This command will checkout remote branch and also switch to the same:

Method-4: Checkout remote branch using a different branch name

What if you would like to checkout a remote branch but name it differently on your local computer? To be able to achieve the name change for your local copy, you will have to use the following syntax;

$ git checkout -b <new_name_for_remote_branch> origin/<remote branch>

First let us perform a fresh fetch to get all the remote branch from the repository to our local workstation:

$ git fetch

Let us use this syntax to checkout our remote branch new-issue-7843 into jira-7843 local branch. At this stage we don't have a jira-7843 local branch and will be created with this command:

deepak@ubuntu:~/git_examples$ git checkout -b jira-7843 origin/new-issue-7843
Branch 'jira-7843' set up to track remote branch 'new-issue-7843' from 'origin'.
Switched to a new branch 'jira-7843'

List the available and active branch:

deepak@ubuntu:~/git_examples$ git branch -a
* jira-7843
  main
  new-feature
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/new-feature
  remotes/origin/new-issue-7843

Note that origin is a standard reference that connects to the remote repository that the project was cloned from. However, this will be different when we will be working with multiple remotes in a branch scenario.

Method-5: To track a remote branch in a new local branch

In some instances, you may require to have your new local branch track the remote copy so that you can easily pull and push changes. You will need to apply the --track option plus the checkout command for it to work.

First perform a fresh git fetch to fetch all the branch details from the repository:

$ git fetch

Here is the syntax that you will use to checkout with --track option:

$ git checkout -t <remote-repo>/< myRemoteBranch>

Currently I have following local and remote branches:

deepak@ubuntu:~/git_examples$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/new-feature
  remotes/origin/new-issue-7843

So let me checkout new-feature remote branch here:

deepak@ubuntu:~/git_examples$ git checkout -t origin/new-feature
Branch 'new-feature' set up to track remote branch 'new-feature' from 'origin'.
Switched to a new branch 'new-feature'

Verify the active and list of remote branches. As you can see we have switched to new-feature remote branch:

deepak@ubuntu:~/git_examples$ git branch -a
  main
* new-feature
  remotes/origin/HEAD -> origin/main
  remotes/origin/main
  remotes/origin/new-feature
  remotes/origin/new-issue-7843

Summary

In this git tutorial we covered following topics:

• Clone git repository
• Fetch git repository branches and checkout remote branch
• Checkout remote branch and save it as a different branch name on the local workstation
• Checkout remote branch and track the changes of remote branch
• List all local and remote branches

Further reading

git-branch - List, create, or delete branches