Skip to content

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

docs(process): record evaluated alternatives for background worktree removal (#2206)

Maximilian Roosb320a3d8fecd
diff --git a/src/commands/process.rs b/src/commands/process.rs
index c9f947700..1bb6b2506 100644
--- a/src/commands/process.rs
+++ b/src/commands/process.rs
@@ -539,6 +539,99 @@ fn parse_trash_entry_timestamp(name: &str) -> Option<u64> {
///
/// When `changed_directory` is false, no placeholder exists, so the background
/// command just removes the staged directory directly.
+///
+/// # Design alternatives evaluated (2026-04)
+///
+/// Two weaknesses in the current design prompted an investigation:
+///
+/// 1. **Silent `rmdir` failure.** If anything lands in the placeholder
+/// during the 1-second sleep (e.g., macOS `.DS_Store`, a filesystem
+/// race, an editor saving against the old path), `rmdir` fails silently
+/// because of `2>/dev/null`, and the empty directory at `original_path`
+/// lingers forever. This was the root cause of an intermittent
+/// `test_bare_repo_merge_workflow` flake.
+/// 2. **"Create then delete" placeholder lifecycle.** wt creates an empty
+/// directory that the background shell removes one second later; its
+/// only purpose is keeping `$PWD` valid for shells (notably Nushell)
+/// that stat it between wt's exit and the wrapper's `cd`.
+///
+/// Two alternatives were prototyped and reviewed; neither was adopted.
+///
+/// ## Option A — Fully deferred cleanup with a pending-removal marker
+///
+/// Sync phase shrinks to: write a `PendingRemoval` marker under
+/// `<git-common-dir>/wt/pending/`, spawn detached `wt internal
+/// finish-removal <marker>`, exit. The detached process sleeps 1 second,
+/// then does rename + prune + `branch -D` + `rm -rf` + marker delete —
+/// the work that today happens synchronously. Concurrent operations
+/// (e.g., `wt switch --create <same-branch>` within the 1-second window)
+/// check for matching markers and force-finish the cleanup inline via a
+/// `finish_blocking_for` helper. Crashed cleanup processes are reclaimed
+/// by extending the existing `sweep_stale_trash` path with a
+/// `sweep_stale_pending` variant.
+///
+/// Benefits: eliminates the placeholder lifecycle entirely (the original
+/// path never disappears during wt's execution, so `$PWD` stays valid
+/// "for free"); no `rmdir` silent-failure mode; marker-based
+/// coordination on the recreate race.
+///
+/// Drawbacks surfaced by Codex review:
+///
+/// - **Data safety (P1).** The clean-check runs sync but the rename
+/// runs ~1 second later. Writes to existing files during that window
+/// (editor save, background build) are silently renamed into trash
+/// and `rm -rf`'d. Today's sync rename keeps that window
+/// microsecond-wide. Mitigation: revalidate cleanliness in the
+/// finisher and bail on dirty — but that turns "remove" into a silent
+/// no-op visible only in log files.
+/// - **Hook timing (P2).** `spawn_hooks_after_remove` runs right after
+/// the sync phase returns. In the deferred design, `post-remove`
+/// hooks fire while `git worktree list` still reports the worktree
+/// and the branch still exists, contrary to the hook's documented
+/// contract. Fix: move hook invocation into the finisher.
+/// - **Retained-branch coordination (P1).** The marker's `branch` field
+/// must be recorded independently of the `delete_branch` flag, or
+/// `finish_blocking_for(Some("feature"), ..)` misses markers whose
+/// branch was retained (`--no-delete-branch`, unmerged safe-delete).
+/// - **Complexity cost.** New module (`src/commands/pending.rs`), new
+/// hidden CLI subcommand (`wt internal finish-removal`), sweep
+/// recovery, coordination calls in `plan_switch`,
+/// `validate_worktree_creation`, and `handle_remove_command`. ~450
+/// lines of new code plus tests.
+///
+/// ## Option B — Sync rename + `rm -rf` instead of `rmdir`
+///
+/// Keep the current sync phase (rename + prune + `branch -D` + create
+/// placeholder), add the pending-removal marker + coordination hooks,
+/// and in this function substitute `rm -rf <placeholder>` for
+/// `rmdir <placeholder> 2>/dev/null`.
+///
+/// Benefits: fixes the flake's root cause (silent-failure mode gone);
+/// inherits marker-based coordination; keeps the data-safety window at
+/// microseconds; keeps hook timing correct.
+///
+/// Drawbacks:
+///
+/// - Doesn't eliminate the "create then delete" placeholder pattern —
+/// just makes its cleanup robust.
+/// - Introduces a narrow new window: if something writes to the
+/// placeholder during the 1-second sleep, `rm -rf` deletes it.
+/// Today's silent `rmdir` accidentally preserves such writes as
+/// orphaned leftovers (ugly but data-preserving). Mitigation:
+/// revalidate emptiness in the finisher and skip `rm -rf` on
+/// non-empty placeholders — turns that accidental preservation into a
+/// deliberate invariant.
+///
+/// ## Decision
+///
+/// Neither was adopted. The flaky test was fixed at the test layer by
+/// teaching `wait_for_worktree_removed` to accept "gone or empty
+/// placeholder" as the success condition — matching what
+/// `assert_worktree_removed` already documents. If flakiness resurfaces
+/// or the visible-placeholder aesthetic becomes a real friction point,
+/// Option B is the low-risk path forward: strictly dominates main
+/// except for the narrow write-into-placeholder edge case, and reuses
+/// most of the pending-module work from Option A.
pub fn build_remove_command_staged(
staged_path: &std::path::Path,
original_path: &std::path::Path,
diff --git a/src/testing/mod.rs b/src/testing/mod.rs
index 8bbb0ec27..ec21521f2 100644
--- a/src/testing/mod.rs
+++ b/src/testing/mod.rs
@@ -2199,25 +2199,52 @@ fn exponential_sleep(attempt: u32) {
ExponentialBackoff::default().sleep(attempt);
}
-/// Assert that a worktree's contents have been removed.
+/// True when a worktree's contents have been removed — either the path
+/// is gone, or it's an empty placeholder directory.
///
-/// After background removal, the path may briefly exist as an empty placeholder
-/// directory (for shell PWD validity). This asserts the contents are gone —
-/// either the path doesn't exist, or it's an empty directory.
-pub fn assert_worktree_removed(path: &Path) {
- // Use read_dir as the single check to avoid a TOCTOU race where the
- // background process removes the placeholder between exists() and read_dir().
- let is_empty_or_gone = match path.read_dir() {
+/// After the instant-removal path renames the worktree into trash, the
+/// original path can linger as an empty placeholder until the background
+/// shell's `sleep 1 && rmdir` runs (the placeholder keeps `$PWD` valid
+/// for shells like Nushell that validate it). The `rmdir` silences
+/// errors with `2>/dev/null` and only removes empty directories, so
+/// under load — or when any stray file (e.g., `.DS_Store`) lands in the
+/// placeholder — the path can remain indefinitely. Production doesn't
+/// care (empty placeholder is harmless); tests that do a strict
+/// `!path.exists()` check would flake.
+fn worktree_contents_removed(path: &Path) -> bool {
+ // Single `read_dir` avoids a TOCTOU race between `exists()` and the
+ // background process removing the placeholder.
+ match path.read_dir() {
Ok(mut entries) => entries.next().is_none(), // empty placeholder
Err(_) => true, // already gone (NotFound or other)
- };
+ }
+}
+
+/// Assert that a worktree's contents have been removed.
+///
+/// Mirrors `worktree_contents_removed`: the path must be either gone
+/// or an empty placeholder.
+pub fn assert_worktree_removed(path: &Path) {
assert!(
- is_empty_or_gone,
+ worktree_contents_removed(path),
"Worktree contents should be removed (empty placeholder OK): {}",
path.display()
);
}
+/// Poll until a worktree's contents have been removed.
+///
+/// Prefer this over `wait_for(..., || !path.exists())` when removal
+/// goes through the instant-removal path (`wt merge`, `wt remove`),
+/// which can leave an empty placeholder directory. See
+/// `worktree_contents_removed`.
+pub fn wait_for_worktree_removed(path: &Path) {
+ wait_for(
+ &format!("worktree contents removed: {}", path.display()),
+ || worktree_contents_removed(path),
+ );
+}
+
/// Wait for a file to exist, polling with exponential backoff.
/// Use this instead of fixed sleeps for background commands to avoid flaky tests.
pub fn wait_for_file(path: &Path) {
diff --git a/tests/integration_tests/bare_repository.rs b/tests/integration_tests/bare_repository.rs
index 4173ec3cd..06749a6af 100644
--- a/tests/integration_tests/bare_repository.rs
+++ b/tests/integration_tests/bare_repository.rs
@@ -1,7 +1,7 @@
use crate::common::{
BareRepoTest, TestRepo, TestRepoBase, canonicalize, configure_directive_files,
configure_git_cmd, configure_git_env, directive_files, repo, setup_temp_snapshot_settings,
- wait_for, wait_for_file, wait_for_file_content, wt_command,
+ wait_for_file, wait_for_file_content, wait_for_worktree_removed, wt_command,
};
use insta_cmd::assert_cmd_snapshot;
use rstest::rstest;
@@ -652,7 +652,12 @@ fn test_bare_repo_merge_workflow() {
}
// Wait for background removal to complete
- wait_for("feature worktree removed", || !feature_worktree.exists());
+ // Use the "gone or empty placeholder" predicate — the instant-removal
+ // path leaves an empty dir behind if the background `rmdir` silently
+ // fails (stray `.DS_Store`, scheduling delay under parallel load).
+ // That placeholder is production-harmless but trips a strict
+ // `!exists()` check.
+ wait_for_worktree_removed(&feature_worktree);
// Verify main worktree still exists and has the feature commit
assert!(main_worktree.exists());