See All Posts on GitHub    « Previously    Next »

Why You Cannot Directly Check Out a Remote Branch in Git

A common point of confusion in Git is the difference between a remote branch and a local branch. You may see a branch such as origin/feature-login and naturally think, "I should be able to check it out."

The important idea is this: origin/feature-login is not a normal local branch. It is a remote-tracking reference that tells your local Git repository what the corresponding branch on the remote repository looked like when Git last updated its information.

1. What Is a Remote Branch?

Suppose your team has a remote repository called origin. Someone has pushed a branch called feature-login to that repository.

After fetching the latest information, your repository might show:

origin/main
origin/feature-login
origin/develop

At first glance, origin/feature-login looks like a branch that you can simply switch to. But it is better to think of it as a remote-tracking reference.

It represents your local record of the branch feature-login on the remote named origin. It is not the same thing as having a local working branch named feature-login.

Remote repository | | branch: feature-login v origin/feature-login | | remote-tracking reference v Local repository feature-login | | local branch v Your working directory

2. What Does git fetch Actually Do?

When you run:

git fetch origin

Git contacts the remote repository and downloads information about commits and branches that you do not yet have locally.

It then updates remote-tracking references such as:

origin/main
origin/feature-login

Importantly, git fetch does not normally create or switch your local working branch.

Think of fetching as saying:

"Tell me what exists on the remote and bring the new commits into my local repository, but don't change the branch I'm currently working on."

3. Why Can't You Treat origin/feature-login Like Your Local Branch?

A local branch is something you normally work on. It has a branch name, moves forward as you create commits, and is associated with your working directory when you check it out.

A remote-tracking reference such as origin/feature-login serves a different purpose. It is Git's local representation of where the remote branch was last observed.

Local branch	Remote-tracking reference
feature-login	origin/feature-login
Used for local development	Represents the remote branch locally
Can be checked out normally	Not intended to be your normal working branch
Moves as you make commits	Moves when Git updates it from the remote
Can have an upstream branch	Usually identifies the upstream branch itself

4. The Solution: Create a Local Branch That Tracks It

If you want to work on the remote branch, the usual approach is to create a local branch that tracks the remote branch.

For example:

git switch -c feature-login --track origin/feature-login

This command does two things:

1. Creates a local branch called feature-login.
2. Configures it to track origin/feature-login.

You now have a normal local branch that you can work on.

Remote branch origin/feature-login | | -- tracks --> | Local branch feature-login | v Working directory

5. What Does "Tracking" Mean?

Tracking is one of the most useful concepts to understand when working with Git branches.

When your local feature-login branch tracks origin/feature-login, Git knows that these two branches are related.

This allows Git to understand what you mean when you run commands such as:

git pull

Instead of having to specify the remote and branch every time, Git can use the configured upstream branch.

Similarly, when you run:

git push

Git can know where the local branch is intended to push its commits.

Tracking does not mean that the two branches are permanently identical. It simply tells Git which remote branch is the upstream counterpart of your local branch.

6. An Easier Way to Create the Tracking Branch

Git provides a convenient shortcut. If the remote branch exists and there is no conflicting local branch with the same name, you can often simply run:

git switch feature-login

Git can recognize that origin/feature-login exists and automatically create a local feature-login branch that tracks it.

The older, widely used equivalent is:

git checkout -b feature-login origin/feature-login

This explicitly says:

• Create a local branch named feature-login.
• Start it from origin/feature-login.
• Check out the newly created local branch.

7. What Happens When You Pull?

Suppose you have created:

feature-login → tracks → origin/feature-login

Someone else then adds commits to the remote branch.

You can update your knowledge of the remote with:

git fetch origin

Your local remote-tracking reference now moves:

origin/feature-login

Your local branch may still be where it was:

feature-login

When you subsequently run:

git pull

Git uses the tracking relationship to determine which remote branch to fetch from and integrate into your current branch.

Before fetch: feature-login -------- A -------- B origin/feature-login -- A -------- B Someone pushes C to remote: feature-login -------- A -------- B origin/feature-login -- A -------- B -------- C After git pull: feature-login -------- A -------- B -------- C origin/feature-login -- A -------- B -------- C

8. What Does "Merge With It" Mean?

The phrase "merge with the remote branch" can be slightly misleading. You do not normally merge directly with a server-side branch.

Instead, Git first represents the remote branch locally as a remote-tracking reference such as:

origin/feature-login

You can then merge that reference into your local branch:

git merge origin/feature-login

For example, imagine your local branch contains:

A --- B --- C
          \
           D --- E    (feature-login)

Meanwhile, the remote-tracking branch has advanced:

A --- B --- C --- F --- G
          \
           D --- E    (feature-login)

Running:

git merge origin/feature-login

tells Git to integrate the commits represented by origin/feature-login into your current local branch.

9. A Typical Workflow

A practical workflow might look like this:

Step 1: Fetch the remote information

git fetch origin

Step 2: See the remote branches

git branch -r

You might see:

origin/main
origin/develop
origin/feature-login

Step 3: Create a local tracking branch

git switch -c feature-login --track origin/feature-login

Step 4: Work normally

git add .
git commit -m "Add login validation"

Step 5: Push your local commits

git push

Because the local branch is tracking origin/feature-login, Git knows where the commits should be pushed.

10. One Important Correction to the Original Statement

The statement:

"You cannot check out a remote branch."

is useful as a beginner-friendly rule, but it is technically a little too absolute.

Git can check out a remote-tracking reference directly. For example, commands such as:

git checkout origin/feature-login

can put you into a state where HEAD is detached.

You can inspect the code, but you are not working on a normal local branch. If you make commits there, Git does not have a local branch name that automatically moves forward with those commits.

This is why the better practical advice is:

Don't use a remote-tracking reference as your normal working branch. Create a local branch that tracks it instead.

11. The Mental Model to Remember

The easiest way to remember the distinction is to think of the three names as different things:

Name	Meaning
feature-login	Your local working branch.
origin/feature-login	Your local record of the remote branch.
origin	The name of the remote repository.

So when someone says:

feature-login tracks origin/feature-login

it means:

Your computer Local branch feature-login | | tracks v Remote-tracking reference origin/feature-login | | represents v Branch on remote repository feature-login

12. The Key Takeaway

A remote branch and a local branch are not the same thing. After git fetch, Git gives you a remote-tracking reference such as origin/feature-login. This lets you see and work with information about the remote branch without making that reference your local working branch.

If you want to develop on that branch, create a local branch from it and configure the local branch to track the remote branch:

git switch -c feature-login --track origin/feature-login

Once the tracking relationship exists, commands such as git pull and git push become much more convenient because Git knows the relationship between your local branch and its remote counterpart.

In one sentence:

origin/feature-login is Git's local reference to a remote branch; to work on it normally, create a local feature-login branch that tracks origin/feature-login.

See All Posts on GitHub    « Previously    Next »