Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(remove): record the dirty-worktree gate as a match-git decision (#3690)

Maximilian Roosf3531042bddd
diff --git a/CLAUDE.md b/CLAUDE.md
index f8ccdb4f2..ef34dbf55 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -60,7 +60,10 @@ Never risk data loss without explicit user consent. A failed command that preser
- **Time-of-check vs time-of-use** — be conservative when there's a gap between the safety check and the operation. `wt merge` verifies clean before rebasing, but files could appear before cleanup — don't force-remove during cleanup.
- **Replace files, never truncate them** — `fs::write` truncates before it writes, so a crash mid-write leaves the file empty. Every write to a file worktrunk can't put back (rc files, shell wrappers, `config.toml`, `approvals.toml`, another tool's `settings.json`) goes through `utils::write_atomically`, which renames a sibling temp file over the target; the spec on that function covers symlinks, mode, and what a rename costs. Regenerable content (the cache, the `-vv` diagnostic report) keeps the plain write.
-These stop where git's own protections stop: `wt merge` and `wt step push` overwrite an ignored file in the destination worktree whose path the incoming commits track, exactly as a `git merge` run there would. Matching git is deliberate — the spec in `src/commands/worktree/push.rs` says why.
+These stop where git's own protections stop, and matching git is deliberate in each case. The named spec says why:
+
+- `wt merge` and `wt step push` overwrite an ignored file in the destination worktree whose path the incoming commits track, exactly as a `git merge` run there would (`src/commands/worktree/push.rs`).
+- Removal's final dirty-worktree gate is answered by the fsmonitor daemon under `core.fsmonitor`, exactly as `git worktree remove`'s own gate is (`src/git/remove.rs`).
Full inventory: FAQ [What files does Worktrunk create?](docs/content/faq.md#what-files-does-worktrunk-create) and [What can Worktrunk delete?](docs/content/faq.md#what-can-worktrunk-delete). Review new code that changes this surface against those sections.
diff --git a/src/git/remove.rs b/src/git/remove.rs
index d0ec9b55e..95291d1ee 100644
--- a/src/git/remove.rs
+++ b/src/git/remove.rs
@@ -35,6 +35,22 @@
//! - [`ForceDelete`](BranchDeletionMode::ForceDelete): run `branch -D`
//! without the integration check.
//!
+//! # The dirty-worktree gate follows git
+//!
+//! Under `core.fsmonitor` the daemon answers step 1's `git status`, so a
+//! daemon returning a stale clean answer would let removal delete uncommitted
+//! work. That is git's own line, not a gap in `wt`: `git worktree remove`
+//! refuses a dirty worktree off the same daemon-served status, and on detected
+//! event loss the builtin daemon forces a client rescan or exits. A stale
+//! clean answer therefore requires an *undetected* loss, which lies to the
+//! user's own `git status` in that worktree just as readily.
+//!
+//! Matching git is the decision. Scoping `-c core.fsmonitor=` to that one call
+//! would make `wt` stricter than the command it replaces, and would restore
+//! the full re-stat the ordering above avoids — the dominant per-removal cost
+//! at rust-lang/rust scale. (`--no-optional-locks` is not that knob: it
+//! governs index-lock acquisition, and git still queries the daemon under it.)
+//!
//! # Example
//!
//! ```no_run