How to fix error: pathspec 'branch-name' did not match any file(s) known to git in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 150 views

This Git error occurs when you try to checkout a branch that doesn't exist locally or hasn't been fetched from the remote repository. The error indicates Git cannot find any branch, file, or reference matching what you specified. Fix it by fetching remote branches first or verifying the branch name.

Quick fix

Fixes error: pathspec 'branch-name' did not match any file(s) known to git

# Fetch all branches and tags from all remotes
git fetch --all

# Now try checking out the branch again
git checkout feature-branch
  1. Fetch all remote branches first
  2. Verify the branch exists and check spelling
  3. Explicitly track and checkout the remote branch
  4. Fix restricted fetch configuration
git — error
# Fetch all branches and tags from all remotes
git fetch --all
# Now try checking out the branch again
git checkout feature-branch
error: pathspec 'branch-name' did not match any file(s) known to git

What this error means

This error occurs when you run `git checkout <branch-name>` or `git switch <branch-name>`, but Git cannot find any branch, file, or reference matching the name you provided. Git treats branch names and file paths similarly in checkout commands, so "pathspec" refers to either. The most common scenario is trying to checkout a remote branch that exists on GitHub, GitLab, or another remote, but hasn't been fetched to your local repository yet. Your local Git only knows about branches it has downloaded references for. This can also happen if: - You mistyped the branch name - The branch was deleted from the remote - Your repository was cloned with limited fetch settings (e.g., shallow clone or single-branch clone) - There are multiple remotes and Git cannot determine which one to use

Typical symptoms

  • git checkout fails with 'pathspec did not match' error
  • git switch cannot find the branch you're trying to access
  • Branch exists on remote (GitHub/GitLab) but checkout fails locally
  • git branch -a doesn't show the expected remote branch
  • Checkout works for some branches but not others
  • CI/CD pipeline fails when checking out a specific branch
  • Recently created branch cannot be checked out by team members

Common causes

  1. Remote branch hasn't been fetched to your local repository yet
  2. Typo in the branch name (case-sensitive on most systems)
  3. Branch was deleted from the remote repository
  4. Repository was cloned with --single-branch or --depth flags limiting available branches
  5. Multiple remotes exist and Git cannot determine which to track
  6. fetch configuration in .git/config is restricted to specific branches
  7. Branch name contains special characters not properly escaped
  8. Local and remote refs are out of sync

How to fix "error: pathspec 'branch-name' did not match any file(s) known to git"

1Fetch all remote branches first

The most common fix is to fetch the latest branch information from the remote:

bash
# Fetch all branches and tags from all remotes
git fetch --all

# Now try checking out the branch again
git checkout feature-branch

If you only want to fetch from a specific remote:

bash
git fetch origin

After fetching, Git will have the remote tracking branches available.

2Verify the branch exists and check spelling

Double-check that the branch name is correct and exists:

bash
# List all local branches
git branch

# List all remote branches
git branch -r

# List ALL branches (local and remote)
git branch -a

# Search for a specific branch pattern
git branch -a | grep -i feature

Branch names are case-sensitive on most systems. Make sure you're using the exact name shown in git branch -a.

Check on GitHub/GitLab:
If the branch should exist but doesn't appear, verify it on the remote's web interface. It may have been deleted or renamed.

3Explicitly track and checkout the remote branch

If simple checkout fails, explicitly create a local branch that tracks the remote:

bash
# Method 1: checkout with explicit tracking
git checkout -b feature-branch origin/feature-branch

# Method 2: Using --track flag
git checkout --track origin/feature-branch

# Method 3: Using git switch (Git 2.23+)
git switch --track origin/feature-branch

This creates a new local branch feature-branch that tracks origin/feature-branch.

4Fix restricted fetch configuration

If your repository was cloned with --single-branch or has restricted fetch settings, update the configuration:

bash
# Check current fetch configuration
git config --get remote.origin.fetch

# If it shows something like +refs/heads/main:refs/remotes/origin/main
# Change it to fetch all branches:
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

# Now fetch all branches
git fetch origin

# Try checkout again
git checkout feature-branch

This is common in CI/CD environments or shallow clones.

5Handle multiple remotes

When you have multiple remotes (e.g., origin and upstream), Git may not automatically determine which remote's branch to track:

bash
# List all remotes
git remote -v

# See which remote has the branch
git branch -r | grep feature-branch
# Output might show:
# origin/feature-branch
# upstream/feature-branch

# Explicitly specify which remote to track
git checkout -b feature-branch origin/feature-branch
# Or
git checkout -b feature-branch upstream/feature-branch

If the same branch name exists on multiple remotes, you must be explicit about which one to use.

6Update remote references and prune stale branches

Sometimes local references become stale. Update them:

bash
# Update remote refs and remove deleted branches
git remote update --prune

# Or using fetch with prune
git fetch --prune

# List branches again
git branch -a

The --prune flag removes local references to branches that no longer exist on the remote. This can also reveal if a branch was deleted.

7For shallow clones, unshallow the repository

If you cloned with --depth, you may need to fetch the full history:

bash
# Check if this is a shallow clone
git rev-parse --is-shallow-repository

# If true, unshallow the repository
git fetch --unshallow

# Now fetch all branches
git fetch --all

# Try checkout again
git checkout feature-branch

Shallow clones are common in CI/CD to save time, but they limit access to full branch history.

Advanced notes

### Understanding Git's Branch Resolution

When you run git checkout branch-name, Git searches for matches in this order:
1. Local branches in .git/refs/heads/
2. Remote tracking branches in .git/refs/remotes/
3. Tags in .git/refs/tags/
4. Files or directories in the working tree

If multiple matches exist (e.g., same name on multiple remotes), Git cannot automatically choose and requires explicit specification.

### The checkout.guess Configuration

Git 2.30+ introduced a configuration option that affects automatic remote branch guessing:

bash
# Check current setting
git config checkout.guess

# If set to false, Git won't guess remote branches
# Enable guessing (default behavior)
git config checkout.guess true

### Difference Between git checkout and git switch

Git 2.23 introduced git switch as a clearer alternative to checkout for branch operations:

| Command | Purpose |
|---------|---------|
| git switch branch | Switch branches only |
| git checkout branch | Switch branches OR restore files |
| git restore file | Restore files only |

Using git switch avoids ambiguity between branches and files.

### Why "pathspec" in the Error?

The term "pathspec" comes from Git's unified handling of paths. A "pathspec" can refer to:
- A branch name (feature-branch)
- A file path (src/index.ts)
- A pattern (*.js)

When Git can't find what you're looking for, it uses this generic term because it doesn't know if you meant a branch or a file.

### CI/CD Considerations

Many CI/CD systems clone repositories with limited history or single branches for performance. If your pipeline needs to checkout different branches:

yaml
# GitHub Actions example
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Fetch all history

# GitLab CI example
variables:
  GIT_DEPTH: 0  # Disable shallow cloning

### Debugging Branch Visibility

bash
# Show detailed remote information
git remote show origin

# List all refs (including those not shown by git branch)
git for-each-ref --format='%(refname)' refs/

# Check if a specific ref exists
git show-ref refs/remotes/origin/feature-branch

Frequently asked questions

What does "error: pathspec 'branch-name' did not match any file(s) known to git" mean?
This error occurs when you run git checkout <branch-name> or git switch <branch-name>, but Git cannot find any branch, file, or reference matching the name you provided. Git treats branch names and file paths similarly in checkout commands, so "pathspec" refers to either. The most common scenario is trying to checkout a remote branch that exists on GitHub, GitLab, or another remote, but hasn't been fetched to your local repository yet.
How do I fix "error: pathspec 'branch-name' did not match any file(s) known to git"?
This Git error occurs when you try to checkout a branch that doesn't exist locally or hasn't been fetched from the remote repository. The error indicates Git cannot find any branch, file, or reference matching what you specified. Fix it by fetching remote branches first or verifying the branch name.
What causes "error: pathspec 'branch-name' did not match any file(s) known to git"?
Remote branch hasn't been fetched to your local repository yet Typo in the branch name (case-sensitive on most systems) Branch was deleted from the remote repository
Is the "error: pathspec 'branch-name' did not match any file(s) known to git" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading