async-doc-hook-autodocs-worktree-locks-branch-checkout

Async doc-update hook spawns an autodocs worktree that locks your branch

Problem

This repo's async post-commit hook ("running doc update in background") materializes its own git worktree (e.g. .claude/worktrees/autodocs-<topic>) and checks out the branch you just committed to. Git only allows a branch to be checked out in ONE worktree, so a subsequent git checkout <that-branch> in your main worktree fails:

fatal: '<branch>' is already used by worktree at
'/…/.claude/worktrees/autodocs-<topic>'

It also surfaces indirectly: a code-review subagent you pointed at the PR may report file paths under .../worktrees/autodocs-<topic>/... — that's the hook's worktree, not yours.

Context / Trigger conditions

• You committed on a feature branch; the commit output included [post-commit] Python files changed — running doc update in background....
• You then try to switch back to that branch (e.g. to apply a review fix) and git refuses.
• A subagent's review cites an autodocs-* path.
• Sibling symptom (different fix): the same hook also leaves index.lock behind → Unable to create '.git/worktrees/<name>/index.lock' → that's rm -f (see See also).

Solution

1. Confirm the hook committed nothing to your branch (it usually only reads/regenerates docs and leaves them uncommitted):

   git rev-parse <branch>            # local tip
   git rev-parse origin/<branch>     # remote tip (if pushed)
   git log --oneline <your-sha>..<branch>   # empty = no extra commits
   

   If local == remote == your commit and the range is empty, the autodocs worktree added nothing — safe to remove.
2. Force-remove the autodocs worktree to free the branch:

   git worktree remove --force .claude/worktrees/autodocs-<topic>
   git worktree list | grep autodocs   # should be gone
   

3. Now checkout works. Clear any leftover lock first if present:

   rm -f .git/worktrees/<your-worktree>/index.lock
   git checkout <branch>