Categories
git git-checkout remote-branch

How do I check out a remote Git branch?

7972

Somebody pushed a branch called test with git push origin test to a shared repository. I can see the branch with git branch -r. How do I check out the remote test branch? I’ve tried:

  • git checkout test, which does nothing
  • git checkout origin/test gives * (no branch)

9

  • 41

    I think this thread is unhelpful. Nothing seems to work, the original question seems to have been lost in many of the answers. I have read every word, tried everything below, and have no idea how to do what the OP wants to do.

    Aug 26, 2014 at 0:16

  • 43

    I feel like I’m taking crazy pills. I’m trying to checkout a branch from an upstream, not just origin, and every recommended answer doesn’t do anything remotely helpful (pun-intended). EDIT – excuse me, the multitude of suggestions contained in the top 2 answers were useless; 3rd one (git branch test origin/test) is what works. Glad the top 2 have 20x the number of votes…

    Mar 9, 2017 at 16:35


  • Maybe useful to someone else: When I used the Atom editor UI to fetch and pull changes, it pulled changes on the “main” branch but did not create a local reference to the second remote branch. Using git fetch on the command line created that reference, then I was able to checkout the branch as per several answers.

    Nov 15, 2021 at 5:19

  • 2

    git fetch then git switch

    Apr 25 at 11:34

  • 1

    This answer should be archived. It’s not useful to show people answers this old. Stackoverflow should have an updated answer button.

    – NickJ

    May 31 at 2:46

10853

The answer has been split depending on whether there is one remote repository configured or multiple. The reason for this is that for the single remote case, some of the commands can be simplified as there is less ambiguity.

Updated for Git 2.23: For older versions, see the section at the end.

With One Remote

In both cases, start by fetching from the remote repository to make sure you have all the latest changes downloaded.

$ git fetch

This will fetch all of the remote branches for you. You can see the branches available for checkout with:

$ git branch -v -a

...
remotes/origin/test

The branches that start with remotes/* can be thought of as read only copies of the remote branches. To work on a branch you need to create a local branch from it. This is done with the Git command switch (since Git 2.23) by giving it the name of the remote branch (minus the remote name):

$ git switch test

In this case Git is guessing (can be disabled with --no-guess) that you are trying to checkout and track the remote branch with the same name.

With Multiple Remotes

In the case where multiple remote repositories exist, the remote repository needs to be explicitly named.

As before, start by fetching the latest remote changes:

$ git fetch origin

This will fetch all of the remote branches for you. You can see the branches available for checkout with:

$ git branch -v -a

With the remote branches in hand, you now need to check out the branch you are interested in with -c to create a new local branch:

$ git switch -c test origin/test

For more information about using git switch:

$ man git-switch

I also created the image below for you to share the differences, look at how to fetch works, and also how it’s different to pull:

enter image description here

Prior to Git 2.23

git switch was added in Git 2.23, prior to this git checkout was used to switch branches.

To checkout out with only a single remote repository:

git checkout test

if there there are multiple remote repositories configured it becomes a bit longer

git checkout -b test <name of remote>/test

10

  • 461

    To expand on this: git doesn’t allow you to work on someone else’s branches. You can only work on your own. So if you want to add to someone else’s branch, you need to create your own “copy” of that branch, which is what the above command does (well, it creates your branch and checks it out, too).

    Nov 23, 2009 at 15:24

  • 154

    If it’s a new remote branch you may need to git fetch before doing this so that git is aware of origin/test

    Nov 4, 2011 at 14:38


  • 65

    …and you would do this with git fetch origin test

    – Andrew

    Jan 22, 2012 at 23:24

  • 23

    Error: “git checkout: updating paths is incompatible with switching branches. Did you intend to checkout origin/test which can not be resolved as commit?”

    – Xeoncross

    Sep 11, 2012 at 20:35


  • 93

    git checkout test will NOT work in modern git if you have multiple remotes which have the same branch name. It can’t know which one to use.

    – masukomi

    Sep 16, 2014 at 15:34

1440

Sidenote: With modern Git (>= 1.6.6), you are able to use just

git checkout test

(note that it is ‘test’ not ‘origin/test’) to perform magical DWIM-mery and create local branch ‘test’ for you, for which upstream would be remote-tracking branch ‘origin/test’.


The * (no branch) in git branch output means that you are on unnamed branch, in so called “detached HEAD” state (HEAD points directly to commit, and is not symbolic reference to some local branch). If you made some commits on this unnamed branch, you can always create local branch off current commit:

git checkout -b test HEAD

A more modern approach as suggested in the comments:

@Dennis: git checkout <non-branch>, for example git checkout origin/test results in detached HEAD / unnamed branch, while git checkout test or git checkout -b test origin/test results in local
branch test (with remote-tracking branch origin/test as upstream) –
Jakub Narębski Jan 9 ’14 at 8:17

emphasis on git checkout origin/test

5

  • 39

    Unsurprising, but this version has been released in the last few years – knowing this syntax can save a lot of time since there’s still a lot of old documentation and comment threads floating around that suggest the older method for doing this.

    – Curtis

    Apr 16, 2012 at 13:24

  • 12

    “modern git”–for the record, (approx) what version are you referring to? Sometimes we have to work on systems running older distros.

    Aug 28, 2012 at 2:30


  • 14

    @aidan If you get a response like error: pathspec 'branch_name' did not match any file(s) known to git. then you should do a git fetch first.

    – Dennis

    Oct 18, 2013 at 0:40

  • 6

    Using git version 1.8.3.msysgit.0 and this doesn’t work for me – did not match any file(s) known to git – I’ve done many git fetches

    – PandaWood

    Dec 3, 2013 at 23:59

  • 12

    @Dennis: git checkout <non-branch>, for example git checkout origin/test results in detached HEAD / unnamed branch, while git checkout test or git checkout -b test origin/test results in local branch test (with remote-tracking branch origin/test as upstream)

    Jan 9, 2014 at 8:17

703

In this case, you probably want to create a local test branch which is tracking the remote test branch:

$ git branch test origin/test

In earlier versions of git, you needed an explicit --track option, but that is the default now when you are branching off a remote branch.

To create the local branch and switch to it, use:

$ git checkout -b test origin/test

2

  • 25

    This will create a local branch without switching to it.

    Oct 16, 2013 at 7:20

  • 1

    In your bash git checkout -b test/origin/test suggestion above, you made want to precede it with a bash git fetch upstream to insure that your local repository knows the remote branch test is there. Otherwise, thanks, everything works as advertised.

    Apr 20 at 17:14