Git Error: Cannot Delete Branch Checked Out or Used by Worktree

Git refuses git branch -d when the branch is still checked out somewhere. Run git branch and git worktree list first — they show whether the block is your current checkout or a linked worktree path.

The sections below are independent scenarios. Pick the one that matches your error message and command output — they are not steps in one lab sequence.

Check What's Blocking Branch Deletion

When to use this: you just ran git branch -d and Git printed a checkout or worktree error.

List local branches and read the markers Git prints beside each name:

git branch

* main
+ feature2
  demo

Git documents two checkout markers:

You cannot delete feature2 while the + shows it is still active elsewhere. You cannot delete a branch marked with * until you switch away in this directory.

List every working tree path that holds a checkout:

git worktree list

/path/to/repo        cc1f6a7 [main]
/path/to/feature-wt  cc1f6a7 [feature2]

Each path with a branch name in brackets is blocking deletion of that branch until that worktree switches away or is removed.

The sections below walk through the checkout and worktree cases in detail.

What "Cannot Delete Branch Checked Out" Means

Git does not allow a branch reference to be deleted while a working tree is actively using that branch. You must first switch that worktree to another branch, detach it, or remove the linked worktree.

You may see either phrasing:

On Git 2.52, deleting the branch you are on in the main repository often prints the worktree form:

git branch -d feature

error: cannot delete branch 'feature' used by worktree at '/path/to/repo'

The fix is the same: free every checkout that still uses the branch, then delete it.

Switch Away, Then Delete the Branch

Scenario: git branch shows * on the branch you want to remove, and no + marker or second path in git worktree list holds that branch.

Move HEAD to another local branch such as main:

git switch main

Confirm the asterisk moved:

git branch

* main
  feature

The feature branch is no longer checked out in this directory, so Git can delete it:

git branch -d feature

Deleted branch feature (was 3fd1f94).

If Git instead reports the branch 'feature' is not fully merged, see the section on unmerged branches below — that is a different error after the checkout block is cleared.

Free the Branch Used by Another Worktree

Scenario: git branch shows + feature2, or git worktree list shows feature2 checked out at a path other than your current directory.

You can keep the linked worktree and switch it away, or remove the worktree when you no longer need it.

Keep the Worktree: Switch Away From the Branch

Change directory to the linked worktree and move it off the branch you want to delete:

cd /path/to/feature-wt

Switch that worktree to another branch:

git switch main

If you only need to free the branch name and do not need another branch checked out there, detach HEAD instead:

git switch --detach

Return to the main repository and delete the branch:

cd /path/to/repo
git branch -d feature2

Worktree No Longer Needed: Remove It

When you do not need the linked directory at all, remove the worktree from the main repository:

git worktree remove /path/to/feature-wt

Then delete the branch:

git branch -d feature2

Deleted branch feature2 (was cc1f6a7).

If git worktree remove refuses, Git is protecting a linked worktree that is not clean. By default, Git removes only a clean linked worktree — if it contains tracked modifications or untracked files, review, commit, or stash anything you need before removing it.

If the Worktree Folder Was Already Deleted

Scenario: someone removed the worktree directory from disk without running git worktree remove, and Git still blocks deletion.

Use git worktree prune only when the linked worktree is genuinely gone and you no longer need that checkout path. Pruning drops orphaned metadata — it does not reconnect a directory you moved elsewhere.

If the worktree was moved rather than deleted, use git worktree repair with the new path instead of pruning it:

git worktree repair /path/to/new/feature-wt

When the directory was deleted and you do not need it back, prune orphaned metadata:

git worktree prune

Then retry git branch -d.

If Git Won't Let You Switch Away

Scenario: git switch fails because Git still considers the branch involved in an unfinished operation — often a merge, rebase, or bisect that prevents leaving the current checkout.

Read what Git reports:

git status

If the status line names an unfinished operation, complete or abort it before switching branches. To cancel the most common blockers:

After the operation completes or aborts, use git switch to move off the branch and delete it.

When git branch -d Says Not Fully Merged

Scenario: you switched away successfully, but delete still fails with a merge warning — not a checkout error.

git branch -d feature

error: the branch 'feature' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D feature'

git branch -d only deletes branches whose commits are reachable from your current branch. To discard the branch anyway:

git branch -D feature

Deleted branch feature (was 3fd1f94).

Use -D only when you are sure those commits are not needed. -D forces deletion when Git considers the branch unmerged — it does not bypass an active checkout. You still must switch every worktree away or remove the linked worktree first.

Troubleshooting

References

Git documentation: git-branch
Git documentation: git-worktree
Git documentation: git-bisect

Summary

When git branch -d fails with cannot delete branch checked out at or cannot delete branch used by worktree, a working tree still has that branch checked out. Run git branch and read * for your current directory and + for another linked worktree, then confirm paths with git worktree list.

If the branch is current here, git switch away and delete again. If another worktree holds the checkout, either cd into that path and switch it to another branch or --detach, or remove the worktree when you no longer need it. Use git worktree prune when the directory was deleted manually, or git worktree repair <new-path> when it was moved.

When git switch itself is blocked, read git status and abort the unfinished operation with the matching command — merge, rebase, cherry-pick, or bisect — before switching. Once every checkout is freed, git branch -d deletes merged branches. A follow-up not fully merged message is a separate check: use git branch -D only when you accept losing unmerged commits, knowing that -D still cannot delete a branch that remains checked out.