git-under-contention

Git Under Contention

Preserve every participant's work when repository state may change concurrently.

Core rule

Treat shared checkout as contested state. Stage exact paths, commit only owned changes, and leave unfamiliar hunks untouched.

Preflight

Run bundled detector before first commit in shared checkout:

python <skill-dir>/scripts/contention_preflight.py
python <skill-dir>/scripts/contention_preflight.py --mine path/owned-by-task

Signals include registered worktrees, recent HEAD movement, pre-staged files, and dirty paths outside owned pathspecs. CONTENTION is not automatic failure – it means use isolated worktree or stricter path ownership.

Skip detector only inside isolated worktree created for current task and still run normal status checks.

Shared-checkout rules

• Inspect git status --porcelain, current branch, top-level path, and staged diff before mutation.
• Stage with git add <path>...; avoid git add ., git add -A, and git commit -a.
• Review git diff --cached --name-only and git diff --cached before commit.
• Commit with explicit pathspec when repository conventions allow it.
• Leave changes outside owned paths unchanged, staged or unstaged.
• Avoid stash in contested checkout because stash captures shared state. Use task worktree or WIP commit on owned branch.
• Fetch before deciding branch freshness; do not reset shared checkout to match remote.
• Push durable work promptly so recovery does not depend on one disk.

Worktree lifecycle

Prefer worktree per task when work is multi-file, long-running, risky, or parallel.

1. Fetch remote and create short-lived branch from intended base.
2. Create worktree at explicit validated path.
3. Record absolute root, branch, and base commit in handoff.
4. Edit, stage exact paths, commit, and push as one durable sequence.
5. Recheck dirty state and unpushed commits before cleanup.
6. Remove worktree only through repository helper when one exists.

Before recursive worktree cleanup, inspect symlinks, junctions, mounts, and dependency links. Remove links safely before recursive deletion so cleanup cannot traverse into another checkout.