Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(push): record that destination-worktree safety matches git (#3614)
Maximilian Roosb8299aca34c3
diff --git a/CLAUDE.md b/CLAUDE.mdindex f3611f46c..a89e88eed 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -60,6 +60,8 @@ 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.+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.## Command Execution Principlesdiff --git a/src/commands/repository_ext.rs b/src/commands/repository_ext.rsindex 7625cc796..ace8377c7 100644--- a/src/commands/repository_ext.rs+++ b/src/commands/repository_ext.rs@@ -62,6 +62,11 @@ pub trait RepositoryCliExt {/// The caller has already established that `target_worktree` exists on disk/// (`MergeContext::prepare` refuses a registered-but-missing worktree), so/// the status read here is free to fail if the directory is gone.+ ///+ /// Ignored files are deliberately out of scope — they're absent from the+ /// `git status --porcelain` read this works from, and matching git there is+ /// the decision, not an oversight. The module spec in+ /// `commands/worktree/push.rs` says why.fn prepare_target_worktree(&self,target_worktree: Option<&PathBuf>,diff --git a/src/commands/worktree/push.rs b/src/commands/worktree/push.rsindex fa37054af..962d8877c 100644--- a/src/commands/worktree/push.rs+++ b/src/commands/worktree/push.rs@@ -3,6 +3,22 @@//! Push changes to target branch with safety checks. Both fast-forward push and//! `--no-ff` merge share common scaffolding (target resolution, fast-forward check,//! stash guard, progress/success output) extracted into [`MergeContext`].+//!+//! # Destination-worktree safety follows git+//!+//! The checks cover what `git status --porcelain` reports: a modified or+//! untracked file at a path the push range changes is refused, and the rest of+//! a dirty tree is autostashed and restored. Ignored files fall outside that+//! report, so a push overwrites one whose path the incoming commits track.+//!+//! That is git's own line, not an oversight, and it holds at the mechanisms+//! actually used: the fast-forward hands the checkout to+//! `receive.denyCurrentBranch=updateInstead`, `--no-ff` syncs with+//! `read-tree -m -u`, and both run git's unpack-trees checks, which refuse to+//! clobber an untracked file and silently overwrite an ignored one — the same+//! split a `git merge` there would produce. Matching git is the decision;+//! don't add an ignored-file probe to make `wt` stricter than the tool it+//! wraps.use std::path::PathBuf;