Fix: “cannot delete branch used by worktree”

The Error

When you try to delete a branch, Git produces this error:

$ git branch -d feature/search
error: Cannot delete branch 'feature/search' checked out at '/home/user/project-search'

The same error appears with git branch -D(force delete). The capitalisation of the flag makes no difference here — Git blocks the deletion either way.

Why This Happens

Git does not allow you to delete a branch that is currently checked out in anyworktree. This is a safety mechanism. If Git deleted the branch while it was checked out, the worktree would be left in a broken state — its HEAD would point to a ref that no longer exists.

The path shown in the error message (e.g., /home/user/project-search) tells you exactly which worktree has that branch checked out. You can confirm by listing all worktrees:

$ git worktree list
/home/user/project         abc1234 [main]
/home/user/project-search  def5678 [feature/search]

Step-by-Step Fix

Option A: Remove the Worktree, Then Delete the Branch

If you no longer need the worktree, remove it first. This is the most common solution.

git worktree remove /home/user/project-search

If the worktree has uncommitted changes, Git will refuse to remove it. You can either commit or discard the changes, or force-remove with --force:

# Force-remove (discards uncommitted changes in that worktree)
git worktree remove --force /home/user/project-search

# Safe delete (only if fully merged)
git branch -d feature/search

# Force delete (even if not merged)
git branch -D feature/search

Option B: Switch the Worktree to a Different Branch

If you still need the worktree but want to free up the branch, switch the worktree to a different branch:

cd /home/user/project-search
git switch main
cd /home/user/project

# Now you can delete the branch
git branch -d feature/search

Option C: The Worktree Directory Was Already Deleted

If you manually deleted the worktree directory (e.g., with rm -rf) but Git still thinks it exists, you need to prune stale worktree references first:

# Clean up stale worktree metadata
git worktree prune

# Now delete the branch
git branch -d feature/search

Quick Reference

# 1. See which worktree has the branch
git worktree list

# 2. Remove the worktree
git worktree remove <path>

# 3. Delete the branch
git branch -d <branch-name>