When mutating shared on-disk state that other processes or threads may touch concurrently (worktree registrations, refs, config files), always serialize the check-then-act sequence behind an explicit, cross-process lock, and never let cleanup code interfere with another holder’s in-progress work.
Concretely:
- Prefer the underlying tool’s native atomic primitives when available (e.g.
git update-ref --no-deref for compare-and-swap on a ref) instead of reimplementing read-modify-write logic yourself; this guarantees a concurrent writer is never silently overwritten.
- When you must implement your own lock, use the strongest primitive the filesystem supports (e.g.
File::lock), but provide a correct fallback (exclusive-create claim files) for filesystems without lock support (NFSv3, etc.), and make sure the fallback is itself race-free.
- Acquire the lock before checking preconditions, and keep it held across the check and the mutation. After releasing a lock (or waiting for another writer’s lock to clear), re-verify the state before performing any dependent cleanup — don’t act on a stale snapshot taken before the lock was released:
// Bad: state may change between check and cleanup
delete_ref(name)?;
remove_config_section(name); // ref might have been recreated by now
// Good: re-check under the lock immediately before mutating
let _lock = acquire_config_lock(path)?;
if ref_absent(name)? {
remove_config_section(name);
}
- Never delete, unlock, or otherwise finalize something you don’t own or that is still in progress elsewhere: a prune/cleanup routine must skip entries marked as locked or still-being-set-up by another process, and exit/cleanup handlers must only release locks or remove claim files for operations that have actually completed (wait with a bounded timeout for in-flight work, don’t force-release it).
- When an operation partially fails and must roll back, order the rollback steps so no other process can ever observe a half-finished, inconsistent state (e.g. remove the piece that makes an entry “listed” last, after everything it depends on is already gone, so a concurrent reader either sees the whole entry or nothing).
- Add tests that simulate concurrent holders (another process holding the lock/claim, a lock released mid-operation, a process killed while holding a claim) to prove the race is actually closed, not just the happy path.