Skip to content

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

perf(prune): fan out the metadata prunes with everything else (#3655)

Maximilian Roos5d106aca90c1
diff --git a/src/commands/step/prune.rs b/src/commands/step/prune.rs
index 9b1730fde..ab299b830 100644
--- a/src/commands/step/prune.rs
+++ b/src/commands/step/prune.rs
@@ -253,12 +253,13 @@ struct RemovalContext<'a> {
/// even when none exists). The removal chain has since moved to the CAS
/// `git update-ref -d`, and neither it nor `git worktree remove` (both the
/// scoped metadata prune and the rename-failure fallback) touches
- /// `.git/config` — verified empirically by inode-watching `.git/config`
- /// across each command — so hook-free removals only spawn readers of
- /// shared repo state and can run concurrently. (`git branch -D` remains
- /// reachable only via `delete_branch_if_safe`'s force arm, which prune
- /// never uses, and its snapshot-miss arm, unreachable here because the
- /// chain captures the snapshot immediately before consulting it.)
+ /// `.git/config`, so hook-free removals never rewrite it and can run
+ /// concurrently. Verified empirically: with `.git/config` made immutable,
+ /// only `git branch -D` reports `could not write config file`.
+ /// (`git branch -D` remains reachable only via `delete_branch_if_safe`'s
+ /// force arm, which prune never uses, and its snapshot-miss arm,
+ /// unreachable here because the chain captures the snapshot immediately
+ /// before consulting it.)
check_lock: &'a RwLock<()>,
}
@@ -275,37 +276,42 @@ struct RemovalContext<'a> {
/// - **`--foreground` worktree candidates** — the foreground path runs a TTY
/// trash-cleanup spinner, and concurrent spinners would fight over the
/// cursor.
-/// - **`StaleDetached` and plan-less `Prunable` candidates** — both call
-/// `prune_worktree_entry()` fail-hard. The exclusion is now conservative:
-/// each call names its own stale entry, so it touches only that
-/// `.git/worktrees/<id>` and can no longer disturb a sibling's. TODO(prune):
-/// move these to the read-side fan-out.
-/// (The fail-soft prune inside `stage_worktree_removal` stays on the read
-/// side, as it always has: a swallowed failure only leaves stale metadata
-/// for the next prune, never data loss. The scan's
-/// `prepare_worktree_removal` can also prune under the read guard when a
-/// Linked item's directory vanished mid-scan; `check_one` `.ok()`s that
-/// prepare, so an error there just deselects the candidate.)
/// - **The current worktree** — deferred until after the fan-out drains and
/// run alone; write for uniformity with its post-switch hooks.
+///
+/// Everything else fans out, including the two candidate shapes that
+/// unregister stale worktree metadata: `StaleDetached`, and the plan-less
+/// `Prunable` candidates whose `prepare_worktree_removal` prunes. Each call
+/// names its own entry, so concurrent prunes are safe against each other and
+/// against the scan — see the concurrency section on
+/// [`prune_worktree_entry`](Repository::prune_worktree_entry).
fn removal_needs_write(
candidate: &Candidate,
plan: Option<&RemovalPlan>,
ctx: &RemovalContext<'_>,
) -> bool {
- match candidate.kind {
- CandidateKind::Current | CandidateKind::StaleDetached => true,
+ // The worktree whose `pre-remove` body and trash-cleanup spinner this
+ // removal would run, `None` when it runs neither.
+ let hook_anchor = match candidate.kind {
+ CandidateKind::Current => return true,
+ // `try_remove` prunes the stale entry and returns before either runs.
+ CandidateKind::StaleDetached => None,
CandidateKind::Other | CandidateKind::BranchOnly => match plan {
- None => true,
- Some(RemovalPlan::Worktree { worktree_path, .. }) => {
- ctx.foreground
- || ctx
- .hook_plan
- .has_hooks_for(worktree_path, &[HookType::PreRemove, HookType::PostRemove])
- }
- Some(RemovalPlan::BranchOnly { .. }) => false,
+ Some(RemovalPlan::Worktree { worktree_path, .. }) => Some(worktree_path.as_path()),
+ Some(RemovalPlan::BranchOnly { .. }) => None,
+ // A plan-less `Prunable` candidate plans inside `try_remove`, so
+ // ask its own path what that plan will decide: an entry whose
+ // directory turns out to still be there plans a full worktree
+ // removal, hooks and spinner and all.
+ None => candidate.path.as_deref(),
},
- }
+ };
+ hook_anchor.is_some_and(|anchor| {
+ ctx.foreground
+ || ctx
+ .hook_plan
+ .has_hooks_for(anchor, &[HookType::PreRemove, HookType::PostRemove])
+ })
}
/// Try to remove a candidate immediately. Returns `Ok(Some(branch_deleted))`
@@ -313,9 +319,10 @@ fn removal_needs_write(
/// skipped (preparation error), `Err` on execution error.
///
/// `plan` is the scan-time `prepare_worktree_removal` result from
-/// [`check_one`]. `Prunable` candidates arrive plan-less and prepare here,
-/// under the write lock, because preparing them prunes stale worktree
-/// metadata. Scan-time plans may be stale by execution; the pre-rename
+/// [`check_one`]. `Prunable` candidates arrive plan-less and prepare here
+/// rather than on the scan, because preparing them prunes stale worktree
+/// metadata and the scan also backs `--dry-run`, which mutates nothing.
+/// Scan-time plans may be stale by execution; the pre-rename
/// `ensure_clean` and the branch-delete CAS re-validate what matters — and the
/// returned [`BranchFate`](crate::commands::worktree::BranchFate) is how a CAS
/// refusal reaches the summary.
@@ -427,8 +434,8 @@ struct CheckOutcome {
/// `None` means not removable (dirty, locked, primary — filtered
/// silently, never reported as "younger than") — except for `Prunable`
/// items, which are always removable but plan in `try_remove`: preparing
- /// them calls `prune_worktree_entry()`, a mutation that must stay
- /// serialized.
+ /// them calls `prune_worktree_entry()`, and this scan also backs
+ /// `--dry-run`, which mutates nothing.
plan: Option<RemovalPlan>,
/// Whether the item passed the removability gate (see `plan`).
removable: bool,
@@ -441,8 +448,7 @@ struct CheckOutcome {
/// One check item's full parallel work: integration + removability + age.
/// Held under the check-lock read guard at the call site so it never overlaps
-/// a write-side removal (hook-bearing or metadata-pruning candidates — see
-/// [`removal_needs_write`]).
+/// a write-side removal (see [`removal_needs_write`]).
#[allow(clippy::too_many_arguments)]
fn check_one(
item: &CheckItem,
diff --git a/src/git/repository/worktrees.rs b/src/git/repository/worktrees.rs
index 8452aeda5..625f1b181 100644
--- a/src/git/repository/worktrees.rs
+++ b/src/git/repository/worktrees.rs
@@ -149,6 +149,22 @@ impl Repository {
/// returns `WorktreeLocked` at the top of its path/current arm and rejects
/// a locked worktree before staging one for removal, and prune's
/// `gather_check_items` never selects one as a candidate.
+ ///
+ /// # Concurrent calls
+ ///
+ /// `wt step prune` calls this from several removals at once. Each names one
+ /// entry, so no call deletes another's `.git/worktrees/<id>`. Git also
+ /// `rmdir`s the containing `.git/worktrees` once the last entry goes, but
+ /// that only succeeds on an already-empty directory: `git worktree remove`
+ /// enumerates the directory before deleting its own entry, and every
+ /// per-worktree command in the removal chain (`git status`, the fsmonitor
+ /// stop) runs while that worktree is still registered, so an emptied
+ /// directory has no in-flight reader left to strand.
+ ///
+ /// A `git worktree list` in another process is the one thing that
+ /// disappearing directory can still fail (`fatal: Invalid path
+ /// '…/.git/worktrees'`, between its readdir and its realpath). That is
+ /// git's own race, and it holds however wt schedules its removals.
pub fn prune_worktree_entry(&self, path: &Path) -> anyhow::Result<()> {
// Every caller's path came from `list_worktrees`, which parses git's
// porcelain as UTF-8, so this only fires if that edge ever stops
diff --git a/tests/integration_tests/step_prune.rs b/tests/integration_tests/step_prune.rs
index 769332538..9048ea3ed 100644
--- a/tests/integration_tests/step_prune.rs
+++ b/tests/integration_tests/step_prune.rs
@@ -1557,8 +1557,8 @@ fn test_prune_fallback_config_race_canary(mut repo: TestRepo) {
/// preparation fails at removal time is skipped silently and the run
/// continues: `try_remove` treats a preparation error as "not selected", not
/// a command failure. Preparing a stale entry prunes its metadata — the
-/// mutation that keeps `Prunable` candidates planning under the write lock
-/// rather than on the scan — and it names the entry (`git worktree remove`)
+/// mutation that keeps `Prunable` candidates planning in `try_remove` rather
+/// than on the `--dry-run`-shared scan — and it names the entry (`git worktree remove`)
/// rather than sweeping the repo, so a `git` shim failing `worktree remove` is
/// the deterministic trigger. Unix-only for the same `CreateProcess` reason as
/// the canary shim above.
@@ -1669,6 +1669,100 @@ fn test_prune_removals_run_concurrently(repo: TestRepo) {
}
}
+/// The removals that unregister stale worktree metadata are on the read side
+/// too, not held back one at a time.
+///
+/// Four stale entries: two carrying a branch (prune's plan-less `Prunable`
+/// candidates, which prune while planning) and two detached (`StaleDetached`,
+/// which prune in place of a removal). Each unregisters its own metadata with
+/// `git worktree remove <path>`, and the shim makes every one of them wait for
+/// all four to start before proceeding. Serialized, the first would wait out
+/// the shim's 15 s timeout and drop a sentinel file, which the test asserts
+/// absent. Unix-only for the same `CreateProcess` shim reason as the canary
+/// above.
+#[cfg(unix)]
+#[rstest]
+fn test_prune_metadata_removals_run_concurrently(mut repo: TestRepo) {
+ repo.commit("initial");
+
+ // At main HEAD, so every entry is same-commit integrated.
+ let mut stale = vec![repo.add_worktree("stale-a"), repo.add_worktree("stale-b")];
+ for name in ["det-a", "det-b"] {
+ let path = repo
+ .root_path()
+ .parent()
+ .unwrap()
+ .join(format!("repo.{name}"));
+ repo.run_git(&[
+ "worktree",
+ "add",
+ "--detach",
+ path.to_str().unwrap(),
+ "HEAD",
+ ]);
+ stale.push(path);
+ }
+ for path in &stale {
+ std::fs::remove_dir_all(path).unwrap();
+ }
+
+ let mut cmd = repo.wt_command();
+ // The removal pool is sized from the rayon thread count; pin it to four so
+ // the barrier can resolve even on a single-core runner (the workers block
+ // in subprocess waits, so four threads don't need four CPUs).
+ cmd.env("RAYON_NUM_THREADS", "4");
+ let git_wrapper_dir = repo.home_path().join("git-wrapper");
+ std::fs::create_dir_all(&git_wrapper_dir).unwrap();
+ write_barrier_worktree_remove_wrapper(&git_wrapper_dir, &which::which("git").unwrap());
+ prepend_path(&mut cmd, &git_wrapper_dir);
+ let barrier_dir = repo.home_path().join("barrier");
+ std::fs::create_dir_all(&barrier_dir).unwrap();
+ cmd.env("WT_TEST_BARRIER_DIR", &barrier_dir);
+ cmd.env("WT_TEST_BARRIER_COUNT", stale.len().to_string());
+
+ let output = cmd
+ .args(["step", "prune", "--yes", "--min-age=0s"])
+ .output()
+ .unwrap();
+ let stderr = String::from_utf8_lossy(&output.stderr);
+
+ assert!(output.status.success(), "prune should succeed:\n{stderr}");
+ let sentinels: Vec<String> = std::fs::read_dir(&barrier_dir)
+ .unwrap()
+ .filter_map(|e| e.ok())
+ .map(|e| e.file_name().to_string_lossy().into_owned())
+ .collect();
+ let started: Vec<&String> = sentinels
+ .iter()
+ .filter(|n| n.starts_with("started-"))
+ .collect();
+ assert_eq!(
+ started.len(),
+ stale.len(),
+ "every stale entry should have pruned its own metadata: {started:?}"
+ );
+ let timeouts: Vec<&String> = sentinels
+ .iter()
+ .filter(|n| n.starts_with("timeout-"))
+ .collect();
+ assert!(
+ timeouts.is_empty(),
+ "a metadata prune waited out the barrier — it ran on the write side: {timeouts:?}"
+ );
+ let list = repo.git_output(&["worktree", "list", "--porcelain"]);
+ assert!(
+ !list.contains("prunable"),
+ "every stale entry should be unregistered; worktrees:\n{list}"
+ );
+ let branches = repo.git_output(&["branch", "--format=%(refname:short)"]);
+ for name in ["stale-a", "stale-b"] {
+ assert!(
+ !branches.lines().any(|branch| branch == name),
+ "{name} should have been deleted; branches:\n{branches}"
+ );
+ }
+}
+
/// The first failing removal aborts the rest of the queue.
///
/// Three integrated orphan branches scan in sorted order (`abort-a` first)
@@ -1836,6 +1930,41 @@ exit 1
std::fs::set_permissions(&path, permissions).unwrap();
}
+/// A `git` shim whose `worktree remove` arms rendezvous with each other (see
+/// `test_prune_metadata_removals_run_concurrently`): each records that it
+/// started, then waits until `$WT_TEST_BARRIER_COUNT` of them have. Everything
+/// else passes through to the real git.
+#[cfg(unix)]
+fn write_barrier_worktree_remove_wrapper(dir: &std::path::Path, real_git: &std::path::Path) {
+ use std::os::unix::fs::PermissionsExt;
+
+ let real_git = shell_escape::unix::escape(real_git.to_string_lossy());
+ let script = format!(
+ r#"#!/bin/sh
+case "$1 $2" in
+ "worktree remove") ;;
+ *) exec {real_git} "$@" ;;
+esac
+: > "$WT_TEST_BARRIER_DIR/started-$(basename "$3")"
+i=0
+while [ "$(ls "$WT_TEST_BARRIER_DIR" | grep -c '^started-')" -lt "$WT_TEST_BARRIER_COUNT" ]; do
+ i=$((i+1))
+ if [ "$i" -gt 300 ]; then
+ : > "$WT_TEST_BARRIER_DIR/timeout-$(basename "$3")"
+ break
+ fi
+ sleep 0.05
+done
+exec {real_git} "$@"
+"#
+ );
+ let path = dir.join("git");
+ std::fs::write(&path, script).unwrap();
+ let mut permissions = std::fs::metadata(&path).unwrap().permissions();
+ permissions.set_mode(0o755);
+ std::fs::set_permissions(&path, permissions).unwrap();
+}
+
/// A `git` shim whose `update-ref -d refs/heads/para-{a,b}` arms rendezvous
/// with each other (see `test_prune_removals_run_concurrently`); everything
/// else passes through to the real git.