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.

Best practices
Illustration of Git branches and version history

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.

Get a tailored plan

Contact us

Join the community

Scan with WeChat
to join the community

Try Guance

Start online and pay only for what you use.

Get started

Choose a Guance plan

Code hosting