How to check out a remote Git branch
A colleague pushed a branch and you want to work on it. In current git that is one command — but only after a fetch, and only if you avoid the one form that leaves you on no branch at all.
The command
$ git fetch
$ git switch feature
branch 'feature' set up to track 'origin/feature'.
Switched to a new branch 'feature'
upstream : origin/feature
git switch noticed that no local
feature exists, found exactly one remote that has one, created a local branch
from it and set the upstream. git checkout feature does the same thing; switch
is the newer, narrower command and is worth preferring because checkout also
does half a dozen unrelated jobs.
The fetch is not optional
before fetch, git branch -r : origin/main
after fetch, git branch -r : origin/feature origin/main
Before fetching, your repository has never heard of the branch, and the command will just tell you the pathspec did not match. Git does not go and look — it only knows what the last fetch told it.
So when a branch somebody swears they pushed does not appear, git fetch is the
first thing to try, not a sign that anything is wrong.
Why a fresh clone shows only one branch
local : main
remote : origin/feature origin/main
This confuses people reasonably often. git clone
downloads everything, but it creates exactly one local branch. The others
are present as remote-tracking refs, which is why git branch looks empty and
git branch -r does not.
Nothing is missing. There is no need to “clone all branches” — you already have
them, and git switch <name> materialises a local branch on demand.
The form that leaves you nowhere
$ git checkout origin/feature
You are in 'detached HEAD' state...
git branch --show-current : ''
That empty output is the symptom: you are not on a branch. origin/feature is a
remote-tracking ref, and checking one out directly puts HEAD at a commit rather
than at a branch.
Everything looks normal until you commit — and then the commit belongs to no
branch. Switch away and it is unreferenced, recoverable only through
git reflog.
Detached HEAD is useful deliberately, for looking at an old commit or building a tag. It is just not what you want when you meant to work on somebody’s branch.
When git cannot guess
The one-word form relies on the name being unambiguous. With two remotes that
both have a feature branch, git refuses rather than picking. Then say which:
$ git switch -c feature --track origin/feature
upstream : origin/feature
-c creates the branch, --track sets the upstream so that a later bare
git push and git pull know where to go. This is also the form to use when
you want a local name different from the remote one — put your name after -c
and the remote branch after --track.
The old spelling, which still works and is what most existing answers show:
$ git checkout -b feature origin/feature
About Netcup (advertisement)
The German host Netcup offers, among other things, affordable and powerful web hosting packages, KVM-based root servers and dedicated servers. With our voucher codes you can save even more (6€ off your first order, 30% off all KVM-based root servers, ...).