Git says index.lock: File exists, and nothing is running git
You go to commit and git refuses: Unable to create '.../.git/index.lock': File exists. It suggests another git process is running. You look, and nothing is. The status shows fine, the diff shows fine, and every command that writes fails.
If you run several coding agents, or any tool that watches your repositories, you will meet this sooner or later. It is worth knowing where the file comes from, because the fix is one line and the cause is avoidable.
A read that writes
git status looks like a read. It is not quite one. To answer quickly next time, it refreshes the index and writes it back, and while it writes it holds index.lock. Normally that takes a moment and the lock is gone before anyone notices.
The trouble starts when that git process is killed partway. A killed process cannot clean up after itself, so an empty index.lock stays behind. From then on every commit, pull, checkout, rebase or worktree removal in that folder fails with "File exists", while git status itself keeps working. So the thing you would use to check on the repository tells you nothing is wrong.
Background tools are the usual culprit. Anything that checks status on a timer and cancels a slow check by killing it will, now and then, kill one at exactly the wrong moment. With one repository that is rare. With a dozen worktrees being checked all day, it stops being rare.
Clearing one you already have
- Make sure nothing is using it. Check that no git process is running in that repository, and that no agent is partway through a commit or a rebase there. A lock that belongs to a live process is doing its job.
- Delete the file. In an ordinary checkout it is
.git/index.lock. In a linked worktree each worktree has its own index, so the lock sits under.git/worktrees/<name>/in the main repository. - Run the command again. Nothing else needs repairing. The lock is an empty marker, not a damaged index.
Stopping it coming back
Git has a switch for exactly this. Set GIT_OPTIONAL_LOCKS=0 in the environment of a process, or pass --no-optional-locks to a command, and git skips every lock it does not strictly need. The refresh-and-write inside status is one of those. Commands that are meant to write, such as commit, checkout and branch, still take the locks they need, so it is safe to set for a tool that mostly reads.
If you have a script or a watcher that polls git status, that is the change to make in it.
What changed in the Director
The DevThrottle Director checks git in the background on every session's worktree, which made it exactly the kind of tool that could leave a lock behind. Since v2.33.0 its background git checks no longer take git's optional lock, so a check that is cut short can no longer leave an index.lock in your folder.
The same release changed when those checks run at all. The Source Control page used to check git every 15 and 30 seconds all day, even while it was hidden. It now does its git work in the background, and only while it is on screen. Fewer checks means fewer chances to be interrupted, and switching between sessions no longer waits on git either.
What the Source Control page shows for each session - the changes badge, the list of changed files, and the worktrees - is on the Source Control page of the docs. The fix itself is listed under v2.33.0 in the changelog.