Skip to content

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

24.5 KB
Raw Blame
//! 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,
            &current_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 { .. }))
        );
    }
}