git-auto-maintenance-recurring-worktree-index-lock

Recurring worktree index.lock from git auto-maintenance

Problem

In a repo with many worktrees and heavy object churn, git's automatic maintenance (maintenance.auto / gc.auto, enabled by default) fires at the start of routine commands once loose-object thresholds are hit. The spawned git gc --auto / git repack / git pack-objects run concurrently with your add/commit/checkout, and the contention leaves a stale .git/worktrees/<name>/index.lock. You rm it, the command works, then the NEXT git command spawns maintenance again and the lock returns — an infuriating loop that looks like "another git process is running" when the other process is git maintaining itself on your behalf.

Context / Trigger Conditions

• fatal: Unable to create '.../worktrees/<name>/index.lock': File exists / "Another git process seems to be running … remove the file manually to continue"
• Removing the lock fixes it for exactly one command, then it recurs
• pgrep -fl "git (gc|maintenance|repack|pack-objects)" shows live maintenance procs
• Repo has many worktrees / frequent fetches / rebases (lots of loose objects)
• It even blocks a plain git checkout -b before any commit (rules out a post-commit hook as the cause — that's the key discriminator vs the async-post-commit-hook skills)

Solution

1. Confirm the lock is STALE, then clear it once. Don't blindly rm — a genuinely in-progress commit would be corrupted. Three cause-agnostic forensics PROVE staleness (any cause: auto-maintenance contention, OR a parallel session's killed/crashed commit):

   LOCK=.git/worktrees/<name>/index.lock          # or .git/index.lock in a plain clone
   lsof "$LOCK"                                    # NO output  => no process holds it open
   [ -s "$LOCK" ] && echo NONEMPTY || echo EMPTY   # 0 bytes    => process died before writing the index snapshot
   ls -la --time-style=full-iso "$LOCK"            # mtime minutes old => not an active commit
   pgrep -fl "git (commit|add|write-tree|gc|maintenance|repack|pack-objects)" | grep -v pgrep
   

   Unheld (lsof empty) + 0-byte + minutes-old = textbook stale → safe rm -f "$LOCK" (git's own error literally says "remove the file manually to continue"). Re-check lsof/size immediately before the rm, then stage-by-explicit-path + commit at once to minimise the re-lock window. NOTE the background gc/pack-objects use their OWN locks (gc.pid, pack lock), NOT index.lock — their mere presence is not a reason to wait.
2. Stop YOUR commands from spawning maintenance — pass the flags INLINE on every git write command for the rest of the session:

   git -c gc.auto=0 -c maintenance.auto=false add <paths>
   git -c gc.auto=0 -c maintenance.auto=false commit -F - <<'EOF'
   ...
   EOF
   git -c gc.auto=0 -c maintenance.auto=false checkout -b <branch> origin/main
   git -c gc.auto=0 -c maintenance.auto=false push -u origin <branch>
   

3. The background gc/repack on the shared object store use their OWN locks (gc.pid, objects pack lock) — separate from the worktree index.lock — so they don't block reads; only your index writes contend. Disabling auto-maintenance on your commands removes the collision.