Check out a remote Git branch
Fetch a remote branch and create a local tracking branch, resolve ambiguous remote names, or inspect the commit in detached HEAD.
Fetch the remote, then create a local branch that tracks the remote branch:
git fetch origin
git switch --track -c feature-x origin/feature-x
This makes feature-x your local working branch and sets origin/feature-x as its upstream. git switch requires Git 2.23 or later; the older equivalent is git checkout --track -b feature-x origin/feature-x.
Let Git infer the remote branch
After fetching, inspect available remote-tracking refs:
git branch -r
git checkout feature-x
If no local feature-x exists and exactly one remote has a matching remote-tracking branch, checkout can create and track it automatically. git switch feature-x offers the same convenience. This guessing behavior can be disabled by configuration.
These are alternative ways to create the branch; do not run every creation command in sequence once the local branch exists.
Resolve a name conflict
When the local name already exists, checking it out switches to that existing branch. Use a different name for a separate review branch:
git switch --track -c feature-x-review origin/feature-x
When several remotes have a branch with the same name, specify the desired remote explicitly. Git does not restrict automatic matching to origin. The checkout.defaultRemote setting can select a preferred remote when a name is ambiguous.
Inspect without creating a local branch
git switch --detach origin/feature-x
# Older syntax: git checkout origin/feature-x
This is useful for reading code or running tests. If you make commits you want to keep, create a branch before moving away from them.
FAQ
Why does checkout say the pathspec did not match?
Fetch from the intended remote and check git branch -r. A narrow fetch configuration, such as one created by --single-branch, may exclude the branch even after a normal fetch. Confirm the branch exists on the server and include it in the fetch refspec if needed.
Will pull and push work afterward?
Check the upstream with git branch -vv. Tracking supplies the usual pull relationship, but push behavior also depends on push.default, push remotes, permissions, and branch-name choices. With a differently named review branch, use an explicit destination rather than assuming a bare push will do what you intend.
Will switching discard local edits?
Git normally refuses a switch that would overwrite conflicting tracked changes or non-ignored untracked files. Ignored untracked files can still be overwritten if the target branch tracks those paths. Save or commit the work you need, and back up important ignored files before switching.
See git-checkout, git-switch, git-fetch, and git-push.
Contact us
Join the community
to join the community
Try Guance
Start online and pay only for what you use.
Get startedChoose a Guance plan