Fix: Unable to create '.git/index.lock'

The Safe Removal Checklist

Run these steps in order. The first three are diagnostic — they will tell you whether removing the lock is safe.

Step 1: Find every Git process running on the repo

# macOS / Linux
ps aux | grep -i 'git'

# Or specifically watch for git processes touching your repo
lsof | grep '/path/to/repo'

If you see any running git processes, do not remove the lock — let them finish, or identify which one is stuck. A long-running rebase or an interactive commit waiting on an editor are the usual suspects.

Step 2: Look at when the lock was created

# Get the timestamp on the lock file
ls -la /path/to/repo/.git/worktrees/feat/index.lock

# Or, if it's a main-repo lock:
ls -la /path/to/repo/.git/index.lock

A lock under 30 seconds old? Wait. It might be a real in-flight operation. A lock older than 5 minutes with no running process? Almost certainly stale.

Step 3: Check if any AI agent or IDE has it open

IDEs run background Git operations. So do AI agents. Either can hold an index lock without you noticing. Quick check:

• VS Code: open the Source Control panel and check if it's spinning
• JetBrains IDEs: bottom-right Git widget shows in-progress operations
• Claude Code, Codex: check if the agent says “Running git command…”

Step 4: Remove the lock

Once you've confirmed nothing legitimate is using it:

# For a worktree-specific lock
rm /path/to/repo/.git/worktrees/feat/index.lock

# For the main repo's lock
rm /path/to/repo/.git/index.lock

Rerun the command that failed. It should succeed.

Step 5: Verify the worktree is intact

# List worktrees — make sure none are marked prunable
git worktree list

# Sanity check the working tree
git status

Why Worktrees Make This More Common

A single-checkout repo has one .git/index.lock. With three worktrees, you have three:

/repo/.git/index.lock                          ← main checkout
/repo/.git/worktrees/feature-a/index.lock      ← worktree A
/repo/.git/worktrees/fix-b/index.lock          ← worktree B

Each worktree has its own index because each has its own working tree. If you run a long-running command (a rebase, a big commit, a merge) in worktree A and at the same time fire off a command in worktree A from a different terminal, you race on that worktree's lock.

The common trigger: an AI agent in one terminal, you in another, both touching the same worktree. The error message is the polite Git equivalent of “please pick one driver per car”.

Prevention

• One driver per worktree. If an AI agent owns a worktree, don't open it in your editor and run Git commands in parallel. Open a different worktree to make your changes.
• Don't share branches across worktrees. Each branch should be checked out in exactly one worktree. See already checked out for the related error.
• Finish interactive operations. An interactive rebase or commit waiting on an editor is holding the lock the entire time. Save and close that editor.
• Avoid heavy IDE auto-features in worktrees you don't actively use. Some IDEs run periodic git fetch on every open worktree. Close the IDE on inactive worktrees.

Close-Cousin Errors

Some related lock-file errors that share the same root cause and the same fix:

• fatal: Unable to create .git/HEAD.lock — typically during a rebase or branch switch
• fatal: Could not write to .git/refs/heads/... — often a stale ref lock; remove the .lock file in the same directory
• Another git process seems to be running — the friendly version of this same error

All three follow the same checklist: find the process, check the timestamp, remove the lock if stale.

If It Keeps Coming Back

Repeated lock errors mean something is repeatedly losing its grip. The most common culprits:

• A crashing background process.Maybe your shell's prompt runs git status every keypress and is timing out. Set GIT_OPTIONAL_LOCKS=0 in your shell to disable lock-taking for non-mutating operations.
• A filesystem with sync issues. Worktrees on network drives, dropbox folders, or cloud sync points are a common source. See best practices for recommended worktree locations.
• A misconfigured AI agent loop. If your AI agent retries Git commands too aggressively after a soft failure, it can race itself. The fix is on the agent config, not on Git.