Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! The `wt remove` command: validate removal targets, approve hooks, and
//! dispatch each removal to the output handler.
//!
//! Target failures are reported independently; later targets still run and
//! the batch exits unsuccessfully. An interrupt cancels the batch immediately,
//! retaining completed removals in the JSON report.
use crate::commands::command_executor::ForegroundStdin;
use std::collections::HashSet;
use std::path::Path;
use anyhow::Context;
use worktrunk::HookType;
use worktrunk::config::UserConfig;
use worktrunk::git::{
BranchDeletionMode, ErrorExt, GitError, Repository, ResolvedWorktree, WorktrunkError,
};
use worktrunk::styling::{eprintln, info_message};
use crate::cli::{RemoveArgs, SwitchFormat};
use crate::output::{
BackgroundFallbackMode, CommandFailure, CommandResult, RemovalExecution, handle_remove_output,
print_json,
};
use super::hook_plan::{ApprovedHookPlan, HookPlanBuilder};
use super::hooks::HookAnnouncer;
use super::repository_ext::RepositoryCliExt;
use super::worktree::{BranchFate, RemovalPlan, compute_worktree_path};
use super::{RemoveTarget, flag_pair};
/// The execution mode `--foreground` selects; the background default falls
/// back to the standard detached `git worktree remove`.
fn removal_execution(foreground: bool) -> RemovalExecution {
if foreground {
RemovalExecution::Foreground
} else {
RemovalExecution::Background(BackgroundFallbackMode::Detached)
}
}
/// Validated removal plans, categorized for ordered execution.
///
/// Multi-worktree removal validates all targets upfront, then executes in order:
/// other worktrees first, branch-only cases next, current worktree last.
struct RemovePlans {
others: Vec<RemovalPlan>,
branch_only: Vec<RemovalPlan>,
current: Option<RemovalPlan>,
errors: Vec<anyhow::Error>,
}
impl RemovePlans {
fn has_valid_plans(&self) -> bool {
!self.others.is_empty() || !self.branch_only.is_empty() || self.current.is_some()
}
fn record_error(&mut self, e: anyhow::Error) {
// The remove command collects per-target errors and surfaces each
// individually (partial-success path). Render the typed
// diagnostic block when present so locked/dirty/etc. errors
// carry their hint, falling back to the short label otherwise.
let rendered = e.render_diagnostic().unwrap_or_else(|| e.to_string());
if !rendered.is_empty() {
eprintln!("{rendered}");
}
self.errors.push(e);
}
}
/// The detached worktree sitting where `branch`'s worktree would go, if any —
/// the one thing a branch-only removal of `branch` can't otherwise mention.
///
/// Detaching a worktree's HEAD severs the only link git records between it and
/// the branch, so `branch` genuinely has no worktree and deleting the ref alone
/// is the right operation. But the directory is still on disk, and `No worktree
/// found for branch <name>` reads as though it isn't. Once the link is gone the
/// `worktree-path` template is all that still connects the two, which is a
/// weaker association than the rest of the module draws — the template records
/// where a worktree *would* go, not that this one belongs to that branch, and
/// [`is_worktree_at_expected_path`] returns false for a detached worktree while
/// [`worktree_display_name`] renders one as `path (detached)` without
/// consulting the template at all. That weakness is why this only ever adds a
/// line: a mention that occasionally points at a coincidence costs nothing,
/// where a refusal built on the same inference would block work.
///
/// Three cases go unmatched, each because naming them would mislead:
///
/// - a worktree checked out on some *other* branch — that branch names it, and
/// it has nothing to do with this removal;
/// - the main worktree, which `wt remove <path>` refuses with nothing to do
/// about it, so the hint would be a dead end. What decides this is whether
/// the hint leads anywhere, not whether the command succeeds: a *locked*
/// worktree refuses too and is named all the same, because that refusal
/// carries the `git worktree unlock` that clears the way. A bare repo has no
/// main worktree, so its default-branch checkout is named like any other;
/// - a prunable entry, whose directory is already gone — `wt step prune`'s to
/// sweep, and nothing to point a user at.
///
/// A template that won't expand yields no expected path and so no match. The
/// branch is known to exist by the time this runs: `prepare_worktree_removal`
/// reports a typo, a deleted branch, or a remote-only name as an error, so a
/// plan to annotate means the lookup already succeeded.
///
/// [`is_worktree_at_expected_path`]: super::worktree::is_worktree_at_expected_path
/// [`worktree_display_name`]: super::worktree::worktree_display_name
fn detached_worktree_for<'a>(
repo: &Repository,
config: &UserConfig,
branch: &str,
worktrees: &'a [worktrunk::git::WorktreeInfo],
) -> Option<&'a Path> {
let expected = compute_worktree_path(repo, branch, config).ok()?;
worktrees
.iter()
.find(|wt| {
wt.branch.is_none()
&& !wt.is_prunable()
&& worktrunk::path::paths_match(&wt.path, &expected)
// A `git_dir` lookup that fails says nothing either way, so
// treat it as linked and name the worktree — an extra line is
// the worst a wrong answer here can cost.
&& repo.worktree_at(&wt.path).is_linked().unwrap_or(true)
})
.map(|wt| wt.path.as_path())
}
/// Validate all removal targets, returning categorized plans.
///
/// Resolves each branch name, determines whether it's the current worktree,
/// another worktree, or branch-only, and prepares the removal plan.
/// Errors are collected (not fatal) to support partial success.
fn validate_remove_targets(
repo: &Repository,
config: &UserConfig,
branches: Vec<String>,
keep_branch: bool,
force_delete: bool,
force: bool,
) -> RemovePlans {
let mut plans = RemovePlans {
others: Vec::new(),
branch_only: Vec::new(),
current: None,
errors: Vec::new(),
};
let current_worktree = match repo.current_worktree().root() {
Ok(path) => dunce::canonicalize(&path).unwrap_or(path),
Err(e) => {
plans.record_error(e);
return plans;
}
};
// Dedupe inputs to avoid redundant planning/execution
let branches: Vec<_> = {
let mut seen = HashSet::new();
branches
.into_iter()
.filter(|b| seen.insert(b.clone()))
.collect()
};
let deletion_mode = BranchDeletionMode::from_flags(keep_branch, force_delete);
let worktrees = repo.list_worktrees().ok();
// Capture once for the validation loop. Validation only reads — actual
// removals run later in `handle_remove_output`, so ref state is stable
// across candidates here. Errors propagate to per-candidate calls, which
// fall back to capturing internally when None.
let snapshot = repo.capture_refs().ok();
let mut seen_targets = HashSet::new();
for branch_name in branches {
let resolved = match repo.resolve_worktree(&branch_name) {
Ok(r) => r,
Err(e) => {
plans.record_error(e);
continue;
}
};
// Branch and path spellings are aliases for one registered worktree.
// Once resolution has produced the Git model's canonical identity,
// plan that target only once regardless of how many aliases were
// supplied.
if resolved
.id()
.is_some_and(|id| !seen_targets.insert(id.clone()))
{
continue;
}
let target = match resolved {
ResolvedWorktree::Worktree { path, .. } => {
// `dunce::canonicalize` keeps the path spelling Git operates
// on; `WorktreeId` is only for matching aliases.
let path_canonical = dunce::canonicalize(&path).unwrap_or(path);
// Remove exactly the resolved worktree by its path. Targeting by
// branch name would resolve an ambiguous branch (one checked out
// in several worktrees via `git worktree add --force`) back to
// git's first-listed worktree — removing the wrong one — whereas
// the path is unambiguous. `prepare_worktree_removal` still
// deletes the branch when it's the sole checkout, and retains it
// otherwise (see its shared-branch handling).
RemoveTarget::WorktreePath(path_canonical)
}
ResolvedWorktree::BranchOnly { branch, .. } => RemoveTarget::BranchOnly(branch),
// Resolution tried the argument as a branch and as a worktree path
// and matched neither, so a directory sitting there is a leftover
// skeleton rather than anything wt can remove. Only a typed
// selector reaches this arm — the picker and `wt step prune` call
// `prepare_worktree_removal` with a branch read off a row, which is
// nobody's path.
ResolvedWorktree::NoWorktreeAtPath { path } => {
plans.record_error(GitError::WorktreeNotFoundAtPath { path }.into());
continue;
}
};
match repo.prepare_worktree_removal(
target,
deletion_mode,
force,
¤t_worktree,
worktrees,
snapshot.as_ref(),
) {
// Bucket the validated result, not the pre-validation resolution:
// a worktree whose directory disappeared degrades to BranchOnly
// during preparation and must run with the other branch-only plans.
Ok(mut result) => {
// A branch whose worktree has since been detached still has no
// worktree — detaching severed the link — so the branch-only
// removal is right. What it can't see is the directory still
// sitting at that branch's templated path, which the output
// would otherwise never mention. Annotate here, where the
// user's typed branch name and the config are both in hand.
if let RemovalPlan::BranchOnly {
branch_name,
detached_worktree,
..
} = &mut result
&& let Some(wts) = worktrees
{
*detached_worktree = detached_worktree_for(repo, config, branch_name, wts)
.map(Path::to_path_buf);
}
match &result {
RemovalPlan::Worktree {
changed_directory: true,
..
} => plans.current = Some(result),
RemovalPlan::Worktree { .. } => plans.others.push(result),
RemovalPlan::BranchOnly { .. } => plans.branch_only.push(result),
}
}
Err(e) => plans.record_error(e),
}
}
// `wt remove <branch> <its-detached-path>` removes that directory in this
// run, so it isn't left behind. Checked after the loop because the path
// argument can come before or after the branch.
let removed: Vec<&Path> = plans
.others
.iter()
.chain(&plans.current)
.filter_map(RemovalPlan::removed_worktree_path)
.collect();
for plan in &mut plans.branch_only {
if let RemovalPlan::BranchOnly {
detached_worktree, ..
} = plan
&& detached_worktree.as_deref().is_some_and(|detached| {
removed
.iter()
.any(|path| worktrunk::path::paths_match(path, detached))
})
{
*detached_worktree = None;
}
}
plans
}
/// Terminate processes whose working directory is under a worktree, for
/// `--reap` (experimental). Discovery, the controlling-terminal / self
/// exclusions, and the `SIGTERM`→`SIGKILL` escalation live in
/// [`worktrunk::git::reap`]; this wrapper renders the user-facing progress.
///
/// Called before the worktree directory is staged/renamed — cwd matching
/// requires the directory at its original path. Best-effort: no candidate,
/// or a survivor that ignored both signals, never blocks the removal.
#[cfg(unix)]
fn reap_worktree_processes(worktree_path: &Path, label: &str) {
use color_print::cformat;
use worktrunk::git::reap;
use worktrunk::styling::{
format_with_gutter, progress_message, success_message, warning_message,
};
let procs = reap::collect_reapable(worktree_path);
if procs.is_empty() {
eprintln!(
"{}",
info_message(cformat!(
"No processes to reap under <bold>{label}</> worktree"
))
);
return;
}
let count = procs.len();
let noun = reap::process_noun(count);
eprintln!(
"{}",
progress_message(cformat!(
"Reaping {count} {noun} under <bold>{label}</> worktree"
))
);
let listing = procs
.iter()
.map(|p| format!("{} {}", p.pid, p.command))
.collect::<Vec<_>>()
.join("\n");
eprintln!("{}", format_with_gutter(&listing, None));
let pids: Vec<u32> = procs.iter().map(|p| p.pid).collect();
let gone = reap::reap_pids(&pids);
match reap::reap_summary(count, gone) {
Ok(msg) => eprintln!("{}", success_message(msg)),
Err(msg) => eprintln!("{}", warning_message(msg)),
}
}
/// Reap the removed worktree's processes when `--reap` is set and the result
/// removed a worktree (branch-only deletions have no directory to scope by).
/// The display label prefers the branch name, falling back to the worktree
/// directory name. No-op on non-Unix, where `--reap` is rejected up front.
fn maybe_reap_result(result: &RemovalPlan, reap_enabled: bool) {
#[cfg(unix)]
if reap_enabled && let Some(path) = result.removed_worktree_path() {
let label = result
.branch_name()
.map(str::to_string)
.or_else(|| path.file_name().map(|n| n.to_string_lossy().into_owned()))
.unwrap_or_else(|| "worktree".to_string());
reap_worktree_processes(path, &label);
}
#[cfg(not(unix))]
let _ = (result, reap_enabled);
}
/// Entry point for the `wt remove` command.
///
/// # Command flow
///
/// 1. **Validate** all target worktrees up front via `prepare_worktree_removal`
/// (clean check, branch-deletion-safety check, force-flag handling).
/// 2. **Approve hooks** (`pre-remove`, `post-remove`, `post-switch`) if
/// running interactively and any hooks are configured.
/// 3. **Dispatch to `handle_remove_output`** per target. For each, the output
/// handler runs `pre-remove` hooks in the worktree, then either:
/// - **Foreground** (`--foreground`): stop fsmonitor → rename into
/// `.git/wt/trash/<name>-<timestamp>/` → prune metadata → delete branch
/// → synchronous `remove_dir_all` on the staged directory.
/// - **Background** (default): stop fsmonitor → rename + prune +
/// synchronous branch delete → spawn a detached drain of the trash
/// directory (`wt _drain-trash`). Cross-filesystem or locked worktrees fall back to
/// `git worktree remove` in the detached process.
/// 4. **Post-remove hooks** run in the background after dispatch.
/// 5. **Internal sweep** (fire-and-forget, after primary output): entries
/// left in `.git/wt/trash/` start another detached drain, and orphaned `git fsmonitor--daemon` processes (worktree gone)
/// are terminated. Runs last so it never delays the user-visible progress
/// or success message. See [`super::process::run_internal_sweep`].
pub fn handle_remove_command(args: RemoveArgs, yes: bool) -> anyhow::Result<()> {
let json_mode = args.format == SwitchFormat::Json;
let verify = args.hooks.resolve();
let config = UserConfig::load().context("Failed to load config")?;
let repo = Repository::current().context("Failed to remove worktree")?;
// CLI flags override config; otherwise fall through to [remove] delete-branch
// (defaults to true).
let project = repo.project_identifier().ok();
let cli_override = flag_pair(args.delete_branch, args.no_delete_branch);
let delete_branch =
cli_override.unwrap_or_else(|| config.remove(project.as_ref()).delete_branch());
// Validate conflicting flags
if !delete_branch && args.force_delete {
let message = if args.no_delete_branch {
"Cannot use --force-delete with --no-delete-branch"
} else {
"Cannot use --force-delete with [remove] delete-branch = false; use --delete-branch to override it"
};
return Err(worktrunk::git::GitError::Other {
message: message.into(),
}
.into());
}
// `--reap` relies on per-process cwd discovery (`lsof`/`ps`), which
// has no cheap Windows equivalent — reject it there rather than
// silently no-op.
#[cfg(not(unix))]
if args.reap {
return Err(anyhow::anyhow!("--reap is not supported on Windows"));
}
// Helper: build and approve, once, the frozen hook plan the
// removal will run. Every hook (`pre-remove` / `post-remove` per
// removed worktree, `post-switch` per post-removal destination) is
// selected from the invoking worktree's `.config/wt.toml` — the
// worktree `wt remove` ran in. `!verify` (`--no-hooks`) or a
// declined prompt yields an empty plan — every executor then runs
// no project hooks.
let approve_remove = |removed_worktree_paths: &[&Path],
destination_paths: &[&Path],
yes: bool|
-> anyhow::Result<ApprovedHookPlan> {
if !verify {
return Ok(ApprovedHookPlan::empty());
}
// Non-fatal: a worktree with no project hooks must remove even
// when the project identifier can't be resolved (the plan ends
// up empty and `approve` never needs it). Matches the pre-plan
// behaviour where the empty-batch fast path ran first.
let project_id = repo.project_identifier().ok();
let pid = project_id.as_ref();
let project_config = repo.load_project_config()?;
let mut builder = HookPlanBuilder::new(project_config.as_ref(), &config, pid);
for &wt_path in removed_worktree_paths {
builder.add(wt_path, &[HookType::PreRemove, HookType::PostRemove]);
}
let mut seen_dests = std::collections::HashSet::new();
for &dest in destination_paths {
if !seen_dests.insert(dest) {
continue;
}
builder.add(dest, &[HookType::PostSwitch]);
}
match builder.finish().approve(pid, yes)? {
Some(plan) => Ok(plan),
None => {
eprintln!(
"{}",
info_message("Commands declined, continuing removal without hooks")
);
Ok(ApprovedHookPlan::empty())
}
}
};
// No argument means `@`, resolved like any other selector.
let branches = if args.branches.is_empty() {
vec!["@".to_string()]
} else {
args.branches
};
// Validate ALL first, then approve, then execute
let plans = validate_remove_targets(
&repo,
&config,
branches,
!delete_branch,
args.force_delete,
args.force,
);
let mut failed = !plans.errors.is_empty();
if !plans.has_valid_plans() {
return Err(WorktrunkError::AlreadyDisplayed { exit_code: 1 }.into());
}
// Early exit for benchmarking time-to-first-output
if std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some() {
return Ok(());
}
// Approve hooks (only if we have valid plans): `pre-remove` /
// `post-remove` anchored at each removed worktree and
// `post-switch` at each destination, all selected from the
// invoking worktree's config — see `approve_remove` above.
// (`destination_targets` is mostly the primary worktree
// repeated; the helper dedups destinations by path.)
let all_plans = || {
plans
.others
.iter()
.chain(&plans.branch_only)
.chain(plans.current.iter())
};
let removed_targets: Vec<&Path> = all_plans()
.filter_map(|r| r.removed_worktree_path())
.collect();
let destination_targets: Vec<&Path> =
all_plans().filter_map(|r| r.destination_path()).collect();
let plan = approve_remove(&removed_targets, &destination_targets, yes)?;
// Execute all validated plans: others first, branch-only next, current last
let show_branch = plans.others.len() + plans.branch_only.len() + plans.current.iter().len() > 1;
let run = |result: &RemovalPlan| -> CommandResult<BranchFate> {
maybe_reap_result(result, args.reap);
let mut announcer = HookAnnouncer::new(&repo, show_branch);
let fate = handle_remove_output(
result,
removal_execution(args.foreground),
ForegroundStdin::Inherit,
&plan,
false,
&mut announcer,
)?;
announcer
.flush()
.map_err(|error| CommandFailure::with_result(error, fate))?;
Ok(fate)
};
let mut json_items = Vec::new();
let mut interrupted = None;
for result in all_plans() {
let (fate, error) = match run(result) {
Ok(fate) => (Some(fate), None),
Err(failure) => (failure.result.map(|result| *result), Some(failure.error)),
};
if json_mode && let Some(fate) = fate {
json_items.push(result.to_json(fate));
}
if let Some(error) = error {
if error.interrupt_signal().is_some() {
interrupted = Some(error);
break;
}
crate::print_command_error(&error);
failed = true;
}
}
if json_mode {
print_json(&json_items)?;
}
if let Some(error) = interrupted {
return Err(error);
}
// Fire-and-forget repo-wide internal cleanup (stale trash +
// orphaned fsmonitor daemons) — runs after primary output so
// it never delays the user-visible progress/success messages.
super::process::run_internal_sweep(&repo);
if failed {
return Err(WorktrunkError::AlreadyDisplayed { exit_code: 1 }.into());
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use worktrunk::testing::TestRepo;
#[test]
fn validation_deduplicates_branch_and_path_aliases() {
let mut test = TestRepo::with_initial_commit();
let worktree = test.add_worktree("feature");
let repo = Repository::at(test.root_path()).unwrap();
let plans = validate_remove_targets(
&repo,
&UserConfig::default(),
vec![
"feature".to_string(),
worktree.to_string_lossy().into_owned(),
],
true,
false,
false,
);
assert!(plans.errors.is_empty());
assert_eq!(plans.others.len(), 1);
assert!(plans.branch_only.is_empty());
assert!(plans.current.is_none());
}
/// Resolution sees a registered worktree, but preparation discovers its
/// directory is gone and degrades the result to BranchOnly. Ordered
/// execution must bucket that returned plan with other branch-only plans,
/// not preserve the stale pre-validation classification.
#[test]
fn validation_buckets_missing_worktree_by_returned_plan() {
let mut test = TestRepo::with_initial_commit();
let missing = test.add_worktree("missing-worktree");
test.create_branch("branch-only");
std::fs::remove_dir_all(&missing).unwrap();
let repo = Repository::at(test.root_path()).unwrap();
let plans = validate_remove_targets(
&repo,
&UserConfig::default(),
vec!["missing-worktree".to_string(), "branch-only".to_string()],
false,
false,
false,
);
assert!(plans.errors.is_empty());
assert!(plans.others.is_empty());
assert!(plans.current.is_none());
assert_eq!(plans.branch_only.len(), 2);
assert!(
plans
.branch_only
.iter()
.all(|plan| matches!(plan, RemovalPlan::BranchOnly { .. }))
);
}
}