How to fix fatal: 'worktree' is locked in Git

First, identify which worktrees are locked and examine their status:

# List all worktrees with verbose output
git worktree list --verbose

The output will show each worktree with its status. Locked worktrees will display "(locked)" after their path:

/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature] (locked)

The verbose flag also displays the lock reason if one was provided when locking.

If you want to allow operations on the worktree, unlock it with:

# Unlock by worktree path
git worktree unlock /path/to/worktree

# Or unlock by the worktree directory name relative to main repo
git worktree unlock ../project-feature

After unlocking, you can perform remove, move, or prune operations on the worktree.

# Verify the worktree is now unlocked
git worktree list

If you want to remove a locked worktree without unlocking it first, use the --force flag twice:

# Force remove a locked worktree
git worktree remove --force --force /path/to/worktree

# Or using shorthand
git worktree remove -f -f /path/to/worktree

Warning: Using double --force bypasses both the lock check and any uncommitted changes check. Make sure you've saved any important work before using this option.

To move a locked worktree to a new location without unlocking, use double --force:

# Force move a locked worktree
git worktree move --force --force /old/path /new/path

# Or using shorthand
git worktree move -f -f /old/path /new/path

This is useful when you need to relocate a worktree from a failing drive or unmounted network share.

If you're trying to create a new worktree at a path that's still registered as locked (perhaps from a deleted worktree), use double --force:

# Force add worktree at a path that's locked
git worktree add --force --force /path/to/worktree feature-branch

Before doing this, make sure the original worktree at that path is truly gone and not just temporarily unavailable.

If the standard unlock command doesn't work, you can manually remove the lock file from the main repository:

# Navigate to your main repository
cd /path/to/main/repo

# List the worktrees directory
ls -la .git/worktrees/

# Find and remove the lock file for the specific worktree
rm .git/worktrees/<worktree-name>/locked

Replace <worktree-name> with the directory name of your worktree (usually the final component of the worktree path).

# Example: if worktree was at /home/user/project-feature
rm .git/worktrees/project-feature/locked

After removing the lock file, run git worktree list to verify the worktree is no longer locked.

If you've manually deleted a worktree directory but Git still tracks it, prune the stale entries:

# Dry run to see what would be pruned
git worktree prune --dry-run

# Actually prune stale worktree administrative files
git worktree prune

Note: git worktree prune will NOT remove locked worktrees, even if their directories are missing. You must unlock or force-remove them first.

# To see verbose output during prune
git worktree prune --verbose

Before unlocking, check if there was a reason provided for the lock:

# Check the lock file content directly
cat .git/worktrees/<worktree-name>/locked

If the file exists but is empty, no reason was given. If it contains text, that's the reason the worktree was locked (e.g., "On network share - do not prune").

When to keep a worktree locked:
- It's on a USB drive or external storage that's sometimes disconnected
- It's on a network share that may be temporarily unavailable
- You want to prevent accidental deletion during cleanup operations

Lock a worktree with a reason:

git worktree lock --reason "On external backup drive" /path/to/worktree