This error occurs when git worktree add cannot find the branch or commit reference you specified. Common causes include the branch not existing locally, shallow clones, or typos in the branch name.
When you run `git worktree add <path> <branch>`, Git tries to check out the specified branch into a new working tree directory. The "fatal: invalid reference" error means Git cannot resolve the branch name or commit reference you provided to an actual commit in your repository. Git worktrees allow you to have multiple working directories attached to a single repository, each checked out to a different branch. This is useful for working on multiple features simultaneously, running tests on one branch while coding on another, or comparing changes across branches without stashing. The reference Git is looking for must exist in your local repository. Unlike `git checkout`, which can automatically create a tracking branch from a remote, `git worktree add` requires the reference to already exist locally (unless you use the `-b` flag to create a new branch). This strict behavior catches many developers off guard, especially in CI/CD environments with shallow or single-branch clones.
First, check what branches are available in your repository:
# List all local branches
git branch
# List all branches including remote tracking branches
git branch -a
# Check if Git can resolve the reference
git rev-parse featureIf your branch only appears as remotes/origin/feature but not as a local branch, that's the problem - Git worktree needs a local reference.
If the branch exists on the remote but not locally, fetch it:
# Fetch all branches from origin
git fetch origin
# Or fetch a specific branch
git fetch origin feature:featureThe second command fetches the remote branch and creates a local branch with the same name.
For Jenkins/CI environments with shallow clones:
# Configure fetch to get all branches
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
# Fetch all branches
git fetch --all
# If you have a shallow clone, unshallow it
git fetch --unshallowUse the -b flag to create a new local branch that tracks the remote:
# Create worktree with a new branch tracking origin/feature
git worktree add -b feature ../feature-worktree origin/feature
# Or if you want the worktree directory named after the branch
git worktree add -b feature ./feature origin/featureThis creates a local branch feature that tracks origin/feature and checks it out into the specified directory.
If you just want to work with the remote branch without creating a local tracking branch, you can use --detach:
# Create a worktree with detached HEAD at the remote branch
git worktree add --detach ../feature-worktree origin/featureThis creates a worktree in detached HEAD state pointing to the same commit as origin/feature. Note that any commits you make will not be on a branch until you create one.
Many CI systems use shallow clones for speed. To fix worktree issues in CI:
Jenkins:
// In Jenkinsfile
checkout([
$class: 'GitSCM',
branches: [[name: '*/main']],
extensions: [[$class: 'CloneOption', shallow: false]],
userRemoteConfigs: [[url: 'https://github.com/user/repo.git']]
])GitLab CI:
# In .gitlab-ci.yml
variables:
GIT_DEPTH: 0 # Disable shallow cloning
GIT_STRATEGY: fetchGitHub Actions:
# In workflow file
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch all historyIf you previously had a worktree that was manually deleted (rm -rf instead of git worktree remove), Git may be confused:
# List current worktrees
git worktree list
# Prune stale worktree information
git worktree prune
# Verify the worktree list is clean
git worktree listAfter pruning, try creating the worktree again.
In bare repositories, you cannot create a worktree for the branch that HEAD points to. Check your setup:
# See what HEAD points to
git symbolic-ref HEAD
# If HEAD points to refs/heads/feature and you want a worktree for feature:
# Option 1: Change HEAD to a different branch first
git symbolic-ref HEAD refs/heads/main
# Option 2: Use a commit hash instead of branch name
git worktree add ../feature-worktree $(git rev-parse feature)If your branch name contains spaces or special characters, quote it properly:
# Branch with spaces (not recommended but possible)
git worktree add "../my worktree" "feature/my branch"
# Branch with slashes (common in Git Flow)
git worktree add ../hotfix-worktree feature/hotfix-123If the error shows only part of your branch name (like "fatal: invalid reference: Library" when using a path with spaces), your path might be getting split. Always quote paths with spaces.
### Understanding Git Worktree References
Git worktree is stricter about references than git checkout. Here's why:
1. No automatic DWIM (Do What I Mean): git checkout feature automatically creates a local branch tracking origin/feature if it exists. git worktree add does not - you must use -b explicitly.
2. FETCH_HEAD doesn't count: If you run git fetch origin feature, the commits are stored in FETCH_HEAD, not as a regular branch. The worktree command won't find them there.
3. Worktrees share the same .git: All worktrees share the same repository database. This means you cannot have the same branch checked out in multiple worktrees simultaneously (Git prevents this to avoid conflicts).
### The worktree.guessRemote Setting
You can make worktree behave more like checkout by enabling remote guessing:
git config worktree.guessRemote trueWith this setting, git worktree add ../feature feature will automatically look for origin/feature if feature doesn't exist locally.
### Worktree Lock for CI/CD
In CI environments where worktrees might be cleaned up unexpectedly:
# Lock a worktree to prevent accidental pruning
git worktree lock ../feature-worktree --reason "CI build in progress"
# Unlock when done
git worktree unlock ../feature-worktree### Repairing Broken Worktrees
If worktrees become disconnected (repository moved, paths changed):
# Repair worktree links
git worktree repair
# Repair with explicit paths
git worktree repair ../old-path ../new-pathwarning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server