Fix 'fatal: Needed a single revision' in Git (2024)

Git throws this when you point to a commit that doesn't exist or isn't accessible. It's usually a typo or a detached HEAD issue. Check your revision and refs.

You're in the middle of setting up a git worktree. You run something like:

git worktree add ../hotfix hotfix/urgent-fix

And git spits back:

fatal: Needed a single revision

This also pops up when you try to checkout a branch that doesn't exist, or when you reference a commit hash that's not in your local repo. Doesn't matter if you're on Linux, macOS, or Windows — it's the same error everywhere.

Root Cause

Git can't find the commit, branch, or tag you're asking for. The fix is almost always one of three things:

A typo in the branch or tag name. You'd be surprised how often hotifx shows up.
The branch only exists on the remote. You haven't fetched it yet, so git doesn't know it.
The commit hash is from a different repo or a shallow clone. You're referencing a commit that git can't see.

In worktrees, the usual culprit is that you're trying to attach the worktree to a branch that's already checked out elsewhere. Git won't let you do that, but the error message is misleading. You get fatal: Needed a single revision instead of something helpful like "branch already checked out."

The Fix

Here's how I approach it. Follow these in order — skip the first if you're sure the branch name is right.

Double-check the branch name. Run:
```
git branch -a
```
This lists all local and remote branches. Compare the output to what you typed. If the branch isn't there, move to step 2.
Fetch the remote branch. If you see remotes/origin/your-branch but not a local one, fetch it:
```
git fetch origin your-branch
```
Then create a local tracking branch:
```
git checkout -b your-branch origin/your-branch
```
Now try the worktree add again. Or if you just need the remote branch, use the full ref in the worktree command:
```
git worktree add ../hotfix origin/hotfix/urgent-fix
```
That works because origin/hotfix/urgent-fix is a valid revision.
Check if the branch is already checked out. This is the worktree-specific gotcha. If the branch is checked out in your main working directory or another worktree, git won't let you use it again. Run:
```
git worktree list
```
Look for your branch in the output. If it's there, you need to either use a different branch or remove the other worktree first. If you want the same code in two places, you can't — git enforces one checkout per branch. Instead, create a new branch from that point:
```
git branch new-fix-branch your-branch
 git worktree add ../new-fix new-fix-branch
```
Check the commit hash. If you're using a specific commit (like a1b2c3d), verify it exists in your repo:
```
git cat-file -t a1b2c3d
```
If that returns an error, the commit isn't there. It might be on the remote but not fetched. Run git fetch --all and try again. If you're in a shallow clone (you used --depth 1), you won't have older commits. You'll need to unshallow:
```
git fetch --unshallow
```
Use the reflog to find what you really want. If you're trying to resurrect a deleted branch or commit, the reflog is your friend:
```
git reflog
```
You'll see a list of recent HEAD positions. Copy a hash and use that in your worktree command:
```
git worktree add ../recovered a1b2c3d
```

If It Still Fails

Okay, you've done all the above and git is still whining. Time to dig a little deeper.

Check for case sensitivity issues. On Linux and macOS (with default settings), branch names are case-sensitive. HotFix and hotfix are different. On Windows, it's usually case-insensitive but don't rely on that.
Look at your git config for weird aliases. Run git config --global --list and see if you've got any alias that might be interfering. I've seen people alias checkout to something custom that breaks the revision lookup.
Try a fresh clone. If you suspect your local repo is corrupted (maybe you had a crash during a fetch), clone it again from the remote. It's annoying, but it's faster than fighting a broken repo. I've had to do this twice in my career, and both times it fixed weird errors like this.
Check if you're in the right directory. This sounds dumb, but I've spent 20 minutes debugging this error only to realize I was in the wrong repo. Run git rev-parse --git-dir to confirm which git directory you're actually in.

One last thing — if you're on a really old git version (pre-2.5), worktrees were experimental and buggy. Upgrade to at least 2.30 or whatever your distro has now. Old git versions produce confusing errors. Don't bother with stack overflow answers that tell you to delete your .git/worktrees folder unless you've confirmed your git version — that's a last resort and can lose data.

I've seen this error trip up junior devs more times than I can count. Most of the time it's a typo. Get the branch name right, fetch if needed, and you'll be fine.