Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Output handlers for worktree operations using the global output context
use std::ffi::OsString;
use std::io::Write;
use std::path::{Path, PathBuf};
use std::process::Stdio;
use anstyle::AnsiColor;
use anyhow::Context as _;
use color_print::cformat;
use worktrunk::shell_exec::{Cmd, shell_cwd};
use worktrunk::styling::{eprint, format_bash_with_gutter, stderr};
use crate::commands::command_executor::CommandContext;
use crate::commands::command_executor::{FailureStrategy, ForegroundStdin};
use crate::commands::hook_plan::{ApprovedHookPlan, execute_planned_hook, register_planned};
use crate::commands::hooks::HookAnnouncer;
use crate::commands::process::{
HookLog, InternalOp, build_drain_trash_command, build_remove_command,
build_remove_placeholder_command, spawn_detached,
};
use crate::commands::template_vars::TemplateVars;
use crate::commands::worktree::hooks::PostRemoveContext;
use crate::commands::worktree::{
BranchFate, RemovalPlan, RetainedReason, SharedBranchCheckout, SwitchBranchInfo, SwitchResult,
};
use worktrunk::config::UserConfig;
use worktrunk::git::GitError;
use worktrunk::git::IntegrationReason;
use worktrunk::git::Repository;
use worktrunk::git::{
BranchDeletionMode, BranchDeletionOutcome, BranchDeletionResult, RemoveOptions,
delete_branch_if_safe, execute_branch_deletion, remove_worktree_with_cleanup,
stage_worktree_removal,
};
use worktrunk::path::{canonicalize_with_parents, format_path_for_display};
use worktrunk::progress::{Progress, format_stats_paren};
use worktrunk::remove_dir::remove_dir_with_progress;
use worktrunk::styling::{
FormattedMessage, eprintln, hint_message, info_message, progress_message, success_message,
suggest_command, verbosity, warning_message,
};
use super::{CommandFailure, CommandResult};
use super::shell_integration::{
compute_shell_warning_reason, explicit_path_hint, git_subcommand_warning,
print_shell_activation_hint, should_show_explicit_path_hint,
};
// ============================================================================
// Foreground Trash Cleanup
// ============================================================================
/// Walk the staged trash directory, unlinking files with a TTY spinner.
///
/// Used by the foreground removal path after `remove_worktree_with_cleanup`
/// renames the worktree into `<git-common-dir>/wt/trash/`. The spinner shows
/// `⠼ Removing N files · X MiB` while the walk proceeds; the returned counts
/// drive the post-op summary so the success message matches the spinner.
///
/// Suppresses the spinner when stderr isn't a TTY (auto-detected by
/// `Progress::start`) or when verbosity ≥ 1 (verbose mode prefers structured
/// output over live updates). The walk itself is best-effort — see
/// [`remove_dir_with_progress`].
fn cleanup_staged_with_progress(staged: &Path) -> (usize, u64) {
let progress = if verbosity() >= 1 {
Progress::disabled()
} else {
Progress::start("Removing")
};
remove_dir_with_progress(staged, &progress);
let totals = progress.totals();
progress.finish();
totals
}
// ============================================================================
// Background Removal Helpers
// ============================================================================
/// The removal parameters shared by [`spawn_background_removal`] and
/// [`execute_instant_removal_or_fallback`]. `branch_name` / `deletion_mode` /
/// `target_branch` drive the freshly-recomputed branch deletion; the rest
/// control the worktree removal itself.
struct BackgroundRemoval<'a> {
worktree_path: &'a Path,
branch_name: Option<&'a str>,
deletion_mode: BranchDeletionMode,
target_branch: Option<&'a str>,
force_worktree: bool,
changed_directory: bool,
/// `true` when the planner already decided the branch would be retained
/// (unmerged, or a `Keep` plan) — `print_hints` has explained why,
/// so [`warn_if_branch_retained`] stays silent on the expected
/// `NotDeleted` outcome and only fires when the deletion command errors.
/// `false` means the planner predicted deletion; a `NotDeleted` here is a
/// race (e.g. `pre-remove` hook advanced the branch) that the user has
/// otherwise no signal for.
planner_expected_retention: bool,
}
/// How a background removal behaves when the rename-into-trash fast path fails.
#[derive(Clone, Copy)]
pub enum BackgroundFallbackMode {
/// Spawn the legacy detached `git worktree remove` — the default for
/// `wt remove`, `wt merge`, and the picker.
Detached,
/// Run the fallback removal and branch deletion synchronously for a
/// non-current worktree. `wt step prune` uses this so a candidate's
/// removal is complete by the time it is reported removed — before the
/// final summary prints, never outliving the prune process.
SynchronousForNonCurrent,
}
/// How [`handle_remove_output`] executes a [`RemovalPlan`]: one axis, one
/// value — inline with chrome, staged-and-detached with chrome, or inline
/// with none.
#[derive(Clone, Copy)]
pub enum RemovalExecution {
/// Remove inline and report actual outcomes: progress message, spinner
/// over the trash cleanup, success message from what really happened.
Foreground,
/// Announce, then stage the worktree into trash and hand its deletion to a
/// detached trash drain; the branch deletion still runs synchronously on the
/// fast path. The mode says what happens when the rename-into-trash fails.
Background(BackgroundFallbackMode),
/// The TUI (picker) path: the same inline removal as `Foreground` with no
/// terminal output, no spinner, and no `cd` directive — skim owns the
/// terminal. Only [`RemovalPlan::Worktree`] arrives here; the picker
/// deletes branch-only rows directly via `execute_branch_deletion`.
Silent,
}
enum BackgroundRemovalPlan {
/// The worktree has been removed and trash cleanup scheduling was attempted.
Staged(anyhow::Result<()>),
/// The detached command still has to remove the worktree.
Deferred(Vec<OsString>),
CompletedSynchronously,
}
/// Cleanup still runs when branch deletion fails after staging the worktree.
struct BackgroundRemovalOutcome {
plan: BackgroundRemovalPlan,
branch_fate: anyhow::Result<BranchFate>,
}
/// Spawn background worktree removal: clean-check, stop fsmonitor,
/// rename-then-prune, spawn a detached trash drain.
///
/// Shared sequence for both detached HEAD and branch background removal paths.
/// The caller is responsible for output messages before this call, and hooks
/// after. An error without a partial fate means removal was neither completed
/// nor scheduled. A partial fate records branch deletion or cleanup scheduling
/// failure after removal, so callers still register teardown. The fate is known synchronously
/// except on the detached fallback, whose branch-deletion child runs after this process exits.
fn spawn_background_removal(
repo: &Repository,
main_path: &Path,
removal: &BackgroundRemoval<'_>,
log_label: &str,
fallback_mode: BackgroundFallbackMode,
) -> CommandResult<BranchFate> {
let spawn = |remove_command: &[OsString], operation: InternalOp| {
spawn_detached(
repo,
main_path,
remove_command,
log_label,
&HookLog::Internal(operation),
)
.map(|_| ())
};
let outcome = execute_instant_removal_or_fallback(repo, removal, fallback_mode, spawn)?;
let branch_fate = outcome.branch_fate.map_err(|error| {
CommandFailure::with_result(error, BranchFate::Retained(RetainedReason::Failed))
});
match outcome.plan {
BackgroundRemovalPlan::Staged(cleanup) => {
// Cleanup was scheduled before branch deletion could wait. Preserve
// the deletion error (including its interrupt signal) if both fail.
branch_fate.and_then(|fate| {
cleanup
.map(|_| fate)
.map_err(|error| CommandFailure::with_result(error, fate))
})
}
BackgroundRemovalPlan::Deferred(command) => {
spawn(&command, InternalOp::Remove)?;
branch_fate
}
BackgroundRemovalPlan::CompletedSynchronously => branch_fate,
}
}
/// Execute instant worktree removal via rename-then-prune.
///
/// This function has side effects: it renames the worktree directory and prunes git metadata.
/// On the fast path, the branch is also deleted synchronously (since after prune, the branch
/// is no longer checked out in any worktree), and the background command is just a trash drain.
/// If rename fails (cross-filesystem, permissions, Windows file locking), either returns the
/// legacy `git worktree remove` command with branch deletion deferred to the background, or
/// runs that fallback synchronously for non-current worktrees when the caller needs the
/// removal complete before it reports success (`wt step prune`).
///
/// Stage cleanup is scheduled before synchronous branch deletion can wait;
/// the caller spawns only deferred removal plans after command preparation.
fn execute_instant_removal_or_fallback(
repo: &Repository,
removal: &BackgroundRemoval<'_>,
fallback_mode: BackgroundFallbackMode,
spawn_cleanup: impl Fn(&[OsString], InternalOp) -> anyhow::Result<()>,
) -> anyhow::Result<BackgroundRemovalOutcome> {
let BackgroundRemoval {
worktree_path,
branch_name,
deletion_mode,
target_branch,
force_worktree,
changed_directory,
planner_expected_retention,
} = *removal;
// Dirty-worktree gate, fsmonitor stop, then the rename into .git/wt/trash/
// (instant on same filesystem) — the same prelude the synchronous
// `remove_worktree_with_cleanup` runs. On the fast path the background
// process is then just a trash drain.
if stage_worktree_removal(repo, worktree_path, branch_name, force_worktree)?.is_some() {
if changed_directory {
// Keep the shell's PWD valid until its cd directive is consumed.
let _ = std::fs::create_dir(worktree_path);
}
// Trash cleanup is independent of branch deletion. Start it before a
// deletion lock wait, and still attempt deletion if scheduling fails.
// A running drain deletes this entry too, so a prune starts one
// drain rather than one per worktree.
let trash_dir = repo.wt_trash_dir();
let cleanup = if worktrunk::git::trash_drain_running(&trash_dir) {
Ok(())
} else {
std::env::current_exe()
.context("Failed to locate Worktrunk executable")
.and_then(|executable| {
spawn_cleanup(
&build_drain_trash_command(executable, repo),
InternalOp::Remove,
)
})
};
// Delete branch synchronously now that prune has removed the worktree metadata.
// Fresh refs, not the pre-hook planning decision: hooks or concurrent
// processes may have advanced the branch (`execute_branch_deletion`).
let fate = if let Some(branch) = branch_name
&& !deletion_mode.should_keep()
{
delete_removed_worktree_branch(
repo,
branch,
worktree_path,
target_branch,
deletion_mode,
planner_expected_retention,
)
} else {
Ok(BranchFate::NotAttempted)
};
// The placeholder protects the shell's PWD until exit. Its delay must
// start after any synchronous branch wait, unlike independent trash.
let placeholder_cleanup = if changed_directory {
spawn_cleanup(
&build_remove_placeholder_command(worktree_path),
InternalOp::RemovePlaceholder,
)
} else {
Ok(())
};
Ok(BackgroundRemovalOutcome {
plan: BackgroundRemovalPlan::Staged(cleanup.and(placeholder_cleanup)),
branch_fate: fate,
})
} else {
if matches!(
fallback_mode,
BackgroundFallbackMode::SynchronousForNonCurrent
) && !changed_directory
{
repo.remove_worktree(worktree_path, force_worktree)?;
let fate = if let Some(branch) = branch_name
&& !deletion_mode.should_keep()
{
delete_removed_worktree_branch(
repo,
branch,
worktree_path,
target_branch,
deletion_mode,
planner_expected_retention,
)
} else {
Ok(BranchFate::NotAttempted)
};
return Ok(BackgroundRemovalOutcome {
plan: BackgroundRemovalPlan::CompletedSynchronously,
branch_fate: fate,
});
}
// Fallback: Git handles cross-filesystem moves and file locking.
// Safe deletion is scheduled only for an integrated branch. The Rust
// child retains a changed tip, then rechecks integration and live topology
// before CAS. Force uses the same child, skipping integration.
let (tail, fate) = match branch_name.filter(|_| !deletion_mode.should_keep()) {
Some(branch) => match build_branch_delete_tail(
repo,
branch,
target_branch,
deletion_mode.is_force(),
) {
Ok(Some(tail)) => (Some(tail), Ok(BranchFate::Deferred)),
Ok(None) => {
warn_if_branch_retained(
branch,
&Ok(BranchDeletionResult {
outcome: BranchDeletionOutcome::NotDeleted,
integration_target: target_branch.unwrap_or("HEAD").to_string(),
}),
planner_expected_retention,
);
(None, Ok(BranchFate::Retained(RetainedReason::Unmerged)))
}
// Removal is independent of branch deletion. Preserve the
// branch error after arranging removal, as on the fast path.
Err(error) => (None, Err(error)),
},
None => (None, Ok(BranchFate::NotAttempted)),
};
let command = build_remove_command(
worktree_path,
force_worktree,
changed_directory,
tail.as_deref(),
);
Ok(BackgroundRemovalOutcome {
plan: BackgroundRemovalPlan::Deferred(command),
branch_fate: fate,
})
}
}
/// Delete a removed worktree's branch, retaining its path on hard failures.
/// The fast staging path and synchronous fallback share this producer.
fn delete_removed_worktree_branch(
repo: &Repository,
branch: &str,
worktree_path: &Path,
target_branch: Option<&str>,
deletion_mode: BranchDeletionMode,
planner_expected_retention: bool,
) -> anyhow::Result<BranchFate> {
let result = execute_branch_deletion(
repo,
branch,
target_branch.unwrap_or("HEAD"),
deletion_mode.is_force(),
);
warn_if_branch_retained(branch, &result, planner_expected_retention);
result
.map(|result| BranchFate::from_outcome(&result.outcome))
.map_err(|error| {
GitError::BranchDeletionFailed {
branch: branch.to_owned(),
removed_worktree: Some(worktree_path.to_path_buf()),
error,
}
.into()
})
}
/// Surface the residual branch when `delete_branch_if_safe` returned an
/// unexpected outcome the user wouldn't otherwise see.
///
/// The worktree has already been removed by the time this runs, so silently
/// dropping the branch-deletion outcome (the prior behavior) left the user
/// with no signal that the branch survived. The fast path, the synchronous
/// fallback, and the detached fallback's known-retained arm (no
/// branch-deletion child to schedule) all route through here so the message
/// is consistent.
///
/// - `Ok(RetainedRaced)`: atomic CAS rejected the delete because the ref
/// tip moved between integration check and delete (a hook, a concurrent
/// push). Always surface — the unmerged commits would otherwise vanish
/// silently from the user's view.
/// - `Ok(RetainedCheckedOut)`: the final topology read found the branch in a
/// worktree. Always surface the path; neither the moved-ref nor unmerged
/// wording describes this outcome.
/// - `Ok(NotDeleted)`: integration check declined the branch. Warn only
/// when the planner predicted deletion (a `pre-remove` hook commit, or
/// similar race) — otherwise `print_hints` has explained the case and a
/// second message would duplicate.
/// - `Ok(ForceDeleted)` / `Ok(Integrated(_))`: succeeded; no message.
/// - `Err`: no warning; the caller propagates the Git error after arranging
/// trash cleanup, so a failed deletion never becomes a successful prune.
fn warn_if_branch_retained(
branch: &str,
result: &anyhow::Result<BranchDeletionResult>,
planner_expected_retention: bool,
) {
let Ok(result) = result else {
return;
};
match &result.outcome {
BranchDeletionOutcome::RetainedCheckedOut { path } => {
eprintln!(
"{}",
retained_checked_out_branch_message(branch, path, true)
);
}
BranchDeletionOutcome::RetainedRaced => {
// The branch tip moved between the integration check and the
// atomic delete (a hook commit, a concurrent push). The
// compare-and-swap refused — fail-closed — so the unmerged
// commits are preserved. Always surface, regardless of planner
// prediction.
eprintln!("{}", retained_raced_branch_message(branch, true));
}
BranchDeletionOutcome::NotDeleted if !planner_expected_retention => {
let cmd = suggest_command("remove", &[branch], &["-D"]);
eprintln!(
"{}",
warning_message(cformat!(
"Removed worktree but kept branch <bold>{branch}</> (not integrated); to delete, run <bold>{cmd}</>"
))
);
}
BranchDeletionOutcome::NotDeleted
| BranchDeletionOutcome::ForceDeleted
| BranchDeletionOutcome::Integrated(_) => {}
}
}
/// Build the Rust branch-deletion child for the detached removal fallback.
///
/// Safe deletion captures the integrated tip and target commit for the child.
/// The child retains a moved tip and rechecks live checkout ownership. Force
/// skips the integration and captured-tip gates.
/// Neither paths nor worktree records are parsed by the shell.
fn build_branch_delete_tail(
repo: &Repository,
branch: &str,
target_branch: Option<&str>,
force_delete: bool,
) -> anyhow::Result<Option<Vec<OsString>>> {
let target = target_branch.unwrap_or("HEAD");
let mut expected_tip = None;
let target = if force_delete {
target.to_string()
} else {
let snapshot = repo.capture_refs()?;
let (effective_target, reason) = repo.integration_reason(&snapshot, branch, target)?;
let Some(branch_ref) = snapshot.local_branch(branch).filter(|_| reason.is_some()) else {
return Ok(None);
};
expected_tip = Some(branch_ref.commit_sha.clone());
// Resolve after integration chooses local or upstream, while HEAD
// still belongs to the invoking checkout rather than the child.
repo.run_command(&[
"rev-parse",
"--verify",
"--end-of-options",
&format!("{effective_target}^{{commit}}"),
])?
.trim()
.to_string()
};
let executable = std::env::current_exe().context("Failed to locate Worktrunk executable")?;
let mut args = vec![
executable.into_os_string(),
"_delete-branch-if-safe".into(),
format!("--branch={branch}").into(),
format!("--target={target}").into(),
];
if let Some(tip) = expected_tip {
args.push(format!("--expected-tip={tip}").into());
}
if force_delete {
args.push("--force-delete".into());
}
Ok(Some(args))
}
/// Complete detached deletion without expanding the foreground's candidate.
/// A moved tip is retained before rechecking integration and checkout ownership.
/// Force still uses Git's checkout-protected branch deletion.
pub(crate) fn delete_branch_from_detached_fallback(
branch: &str,
target: &str,
expected_tip: Option<&str>,
force_delete: bool,
) -> anyhow::Result<()> {
let repo = Repository::current()?;
let snapshot = repo.capture_refs()?;
let result = if expected_tip.is_some_and(|tip| {
snapshot
.local_branch(branch)
.map(|branch| branch.commit_sha.as_str())
!= Some(tip)
}) {
BranchDeletionResult {
outcome: BranchDeletionOutcome::RetainedRaced,
integration_target: target.to_string(),
}
} else {
delete_branch_if_safe(&repo, &snapshot, branch, target, force_delete)?
};
warn_if_branch_retained(branch, &Ok(result), false);
Ok(())
}
// ============================================================================
// Switch Output Handlers
// ============================================================================
/// Format a switch message based on what was created
///
/// # Message formats
/// - Branch + worktree created (`--create`): "Created branch X from Y and worktree @ path"
/// - Branch from remote + worktree (DWIM): "Created branch X (tracking remote) and worktree @ path"
/// - Worktree only created: "Created worktree for X @ path"
/// - Switched to existing: "Switched to worktree for X @ path"
fn format_switch_message(
branch: &str,
path: &Path,
worktree_created: bool,
created_branch: bool,
base_branch: Option<&str>,
from_remote: Option<&str>,
) -> String {
let path_display = format_path_for_display(path);
if created_branch {
// --create flag: created branch and worktree
match base_branch {
Some(base) => cformat!(
"Created branch <bold>{branch}</> from <bold>{base}</> and worktree @ <bold>{path_display}</>"
),
None => {
cformat!("Created branch <bold>{branch}</> and worktree @ <bold>{path_display}</>")
}
}
} else if let Some(remote) = from_remote {
// DWIM from remote: created local tracking branch and worktree
cformat!(
"Created branch <bold>{branch}</> (tracking <bold>{remote}</>) and worktree @ <bold>{path_display}</>"
)
} else if worktree_created {
// Local branch existed, created worktree only
cformat!("Created worktree for <bold>{branch}</> @ <bold>{path_display}</>")
} else {
// Switched to existing worktree
cformat!("Switched to worktree for <bold>{branch}</> @ <bold>{path_display}</>")
}
}
struct SwitchOutputContext {
path: PathBuf,
path_display: String,
branch: String,
shell_warning_reason: Option<String>,
user_wont_be_in_worktree: bool,
is_git_subcommand: bool,
}
fn build_switch_output_context(
result: &SwitchResult,
branch_info: &SwitchBranchInfo,
change_dir: bool,
) -> anyhow::Result<SwitchOutputContext> {
let path = super::to_logical_path(result.path());
let path_display = format_path_for_display(&path);
let branch = branch_info
.branch
.clone()
.unwrap_or_else(|| "detached worktree".to_string());
let is_git_subcommand = crate::is_git_subcommand();
let is_shell_integration_active = super::is_shell_integration_active();
let shell_warning_reason = if !change_dir || is_shell_integration_active {
None
} else if is_git_subcommand {
Some("ran git wt; running through git prevents cd".to_string())
} else {
Some(compute_shell_warning_reason()?)
};
let user_wont_be_in_worktree = !change_dir || shell_warning_reason.is_some();
Ok(SwitchOutputContext {
path,
path_display,
branch,
shell_warning_reason,
user_wont_be_in_worktree,
is_git_subcommand,
})
}
fn print_switch_directory_hint(branch: &str, is_git_subcommand: bool) -> anyhow::Result<()> {
if is_git_subcommand {
eprintln!("{}", hint_message(git_subcommand_warning()));
} else if super::retired_shell_wrapper_active() {
super::print_outdated_shell_wrapper_hint_once();
} else if should_show_explicit_path_hint()? {
eprintln!("{}", hint_message(explicit_path_hint(branch)));
}
Ok(())
}
fn handle_switch_already_at_output(ctx: &SwitchOutputContext) -> Option<PathBuf> {
eprintln!(
"{}",
info_message(cformat!(
"Already on worktree for <bold>{}</> @ <bold>{}</>",
ctx.branch,
ctx.path_display
))
);
None
}
fn handle_switch_existing_output(ctx: &SwitchOutputContext) -> anyhow::Result<Option<PathBuf>> {
if let Some(reason) = &ctx.shell_warning_reason {
eprintln!(
"{}",
warning_message(cformat!(
"Worktree for <bold>{}</> @ <bold>{}</>, but cannot change directory — {reason}",
ctx.branch,
ctx.path_display
))
);
print_switch_directory_hint(&ctx.branch, ctx.is_git_subcommand)?;
} else if ctx.user_wont_be_in_worktree {
eprintln!(
"{}",
info_message(cformat!(
"Worktree for <bold>{}</> @ <bold>{}</> (directory change disabled)",
ctx.branch,
ctx.path_display
))
);
} else {
eprintln!(
"{}",
info_message(format_switch_message(
&ctx.branch,
&ctx.path,
false, // worktree_created
false, // created_branch
None,
None,
))
);
}
Ok(ctx.user_wont_be_in_worktree.then(|| ctx.path.clone()))
}
fn maybe_print_worktree_path_hint(created_branch: bool) {
if !created_branch {
return;
}
if let Ok(repo) = worktrunk::git::Repository::current() {
let has_custom_config = UserConfig::load()
.map(|c| {
c.has_custom_worktree_path()
|| repo
.project_identifier()
.ok()
.is_some_and(|p| c.has_project_worktree_path(&p))
})
.unwrap_or(false);
if !has_custom_config && !repo.has_shown_hint("worktree-path") {
let hint = hint_message(cformat!(
"To customize worktree locations, run <underline>wt config create</>"
));
eprintln!("{}", hint);
let _ = repo.mark_hint_shown("worktree-path");
}
}
}
fn handle_switch_created_output(
ctx: &SwitchOutputContext,
created_branch: bool,
base_branch: Option<&str>,
from_remote: Option<&str>,
) -> anyhow::Result<Option<PathBuf>> {
eprintln!(
"{}",
success_message(format_switch_message(
&ctx.branch,
&ctx.path,
true, // worktree_created
created_branch,
base_branch,
from_remote,
))
);
maybe_print_worktree_path_hint(created_branch);
if let Some(reason) = &ctx.shell_warning_reason {
eprintln!(
"{}",
warning_message(cformat!("Cannot change directory — {reason}"))
);
print_switch_directory_hint(&ctx.branch, ctx.is_git_subcommand)?;
}
Ok(ctx.user_wont_be_in_worktree.then(|| ctx.path.clone()))
}
struct BranchDeletionDisplay {
result: BranchDeletionResult,
show_unmerged_hint: bool,
}
/// The canonical "branch retained because unmerged" info + hint lines, as an
/// `(info, hint)` pair. [`print_retained_unmerged_branch`] prints them; the
/// picker stashes them via `stash_retained_unmerged_branch` (it can't print
/// mid-render) from its branch-only keep path — a `/ branch` row whose unmerged
/// branch `SafeDelete` declines to delete stays put, so this explains the no-op.
/// (A worktree removal that keeps its branch transforms the row to `/ branch`
/// live instead, with no stashed message.) Shared so the emit paths can't drift
/// in wording, flag, or styling.
pub(crate) fn retained_unmerged_branch_messages(branch_name: &str) -> (String, String) {
let info = info_message(cformat!(
"Branch <bold>{branch_name}</> retained; has unmerged changes"
))
.to_string();
let cmd = suggest_command("remove", &[branch_name], &["-D"]);
let hint = hint_message(cformat!(
"To delete the unmerged branch, run <underline>{cmd}</>"
))
.to_string();
(info, hint)
}
fn print_retained_unmerged_branch(branch_name: &str) {
let (info, hint) = retained_unmerged_branch_messages(branch_name);
eprintln!("{info}");
eprintln!("{hint}");
}
/// Explain that the branch was kept because another worktree still has it
/// checked out. Removing this worktree can't free a ref that's live elsewhere,
/// so the branch is retained and the surviving checkout is named — the state is
/// only reachable through `git worktree add --force`, so the user may not
/// remember creating it.
///
/// Info by default: nothing went wrong, and this reads as a sibling of
/// [`retained_unmerged_branch_messages`], the other "kept the branch, here's
/// why" line. A refused `-D` is different — `-D` overrides every other
/// retention wt has, so one that doesn't delete is unexpected and warns.
fn print_branch_checked_out_elsewhere(branch_name: &str, shared: &SharedBranchCheckout) {
let path = format_path_for_display(&shared.path);
let message = if shared.refused_force_delete {
warning_message(cformat!(
"Branch <bold>{branch_name}</> retained despite <bold>-D</>; still checked out @ <bold>{path}</>"
))
.to_string()
} else {
info_message(cformat!(
"Branch <bold>{branch_name}</> retained; still checked out @ <bold>{path}</>"
))
.to_string()
};
eprintln!("{message}");
}
/// The canonical "branch retained because the atomic CAS delete was refused"
/// warning. The ref moved between the integration check and the delete (a hook
/// commit, a concurrent push), so the integrated branch is kept fail-closed
/// rather than dropping the new commits. Shared across the worktree-removal and
/// branch-only emit paths so the wording, flag, and styling can't drift.
///
/// `removed_worktree` selects the lead-in: the worktree has already been removed
/// on the worktree-removal paths, but the branch-only path never had one.
fn retained_raced_branch_message(branch_name: &str, removed_worktree: bool) -> String {
let lead_in = if removed_worktree {
"Removed worktree but kept branch"
} else {
"Kept branch"
};
let cmd = suggest_command("remove", &[branch_name], &["-D"]);
warning_message(cformat!(
"{lead_in} <bold>{branch_name}</> (moved during deletion); inspect commits, then run <bold>{cmd}</> if safe"
))
.to_string()
}
/// The canonical message for a branch retained by the final topology read.
///
/// Unlike [`retained_raced_branch_message`], this is not a ref-tip race and
/// does not suggest `-D`: Git refuses to delete a branch while the named
/// worktree holds it. The path is the actionable explanation.
fn retained_checked_out_branch_message(
branch_name: &str,
path: &Path,
removed_worktree: bool,
) -> String {
let lead_in = if removed_worktree {
"Removed worktree but retained branch"
} else {
"Retained branch"
};
let path = format_path_for_display(path);
warning_message(cformat!(
"{lead_in} <bold>{branch_name}</>; checked out @ <bold>{path}</>"
))
.to_string()
}
/// Handle the result of a branch deletion attempt.
///
/// Converts a deletion attempt into structured display data:
/// - `NotDeleted`: We checked and chose not to delete (not integrated) — sets
/// `show_unmerged_hint`.
/// - `RetainedCheckedOut`: the final fresh topology read found a checkout.
/// Callers surface its path, not the unmerged hint.
/// - `RetainedRaced`: integration check passed but the atomic CAS delete was
/// refused because the ref moved (a hook or concurrent process advanced it).
/// Callers surface this with [`retained_raced_branch_message`], not the
/// unmerged hint, so it is *not* folded into `show_unmerged_hint`.
/// - `Err(e)`: return one contextual diagnostic for the caller to render.
fn handle_branch_deletion_result(
result: anyhow::Result<BranchDeletionResult>,
branch_name: &str,
) -> anyhow::Result<BranchDeletionDisplay> {
let result = result.map_err(|error| GitError::BranchDeletionFailed {
branch: branch_name.to_owned(),
removed_worktree: None,
error,
})?;
Ok(BranchDeletionDisplay {
show_unmerged_hint: matches!(result.outcome, BranchDeletionOutcome::NotDeleted),
result,
})
}
struct FlagNote {
text: String,
symbol: Option<String>,
suffix: String,
}
impl FlagNote {
fn empty() -> Self {
Self {
text: String::new(),
symbol: None,
suffix: String::new(),
}
}
fn text_only(text: impl Into<String>) -> Self {
Self {
text: text.into(),
symbol: None,
suffix: String::new(),
}
}
fn with_symbol(
text: impl Into<String>,
symbol: impl Into<String>,
suffix: impl Into<String>,
) -> Self {
Self {
text: text.into(),
symbol: Some(symbol.into()),
suffix: suffix.into(),
}
}
fn after(&self, color: AnsiColor) -> String {
match &self.symbol {
Some(s) => match color {
AnsiColor::Cyan => cformat!("{}<cyan>{}</>", s, self.suffix),
AnsiColor::Green => cformat!("{}<green>{}</>", s, self.suffix),
_ => format!("{s}{}", self.suffix),
},
None => String::new(),
}
}
}
/// Get flag acknowledgment note for remove messages
///
/// `target_branch`: The branch we checked integration against (shown in reason)
fn flag_note(
deletion_mode: BranchDeletionMode,
outcome: &BranchDeletionOutcome,
target_branch: Option<&str>,
) -> FlagNote {
if deletion_mode.should_keep() {
return FlagNote::text_only(" (--no-delete-branch)");
}
match outcome {
BranchDeletionOutcome::NotDeleted
| BranchDeletionOutcome::RetainedCheckedOut { .. }
| BranchDeletionOutcome::RetainedRaced => FlagNote::empty(),
BranchDeletionOutcome::ForceDeleted => FlagNote::text_only(" (--force-delete)"),
BranchDeletionOutcome::Integrated(reason) => {
let Some(target) = target_branch else {
return FlagNote::empty();
};
let symbol = reason.symbol();
let desc = reason.description();
FlagNote::with_symbol(
cformat!(" ({desc} <bold>{target}</>,"),
cformat!(" <dim>{symbol}</>"),
")",
)
}
}
}
/// Show switch message when changing directory after worktree removal.
///
/// When shell integration is not active, warns that cd cannot happen.
/// This is important for remove/merge since the user would be left in a deleted directory.
///
/// # Warning Message Format
///
/// Uses the standard "Worktree for X @ path, but cannot change directory —
/// {reason}" pattern, the same shape `wt switch` uses for an existing worktree.
/// Naming the destination matters more here than anywhere else: the removal
/// deleted the directory the caller is standing in, and unless a post-merge or
/// post-remove hook announcement happens to name its working directory, no
/// other line of the run prints a path to move to.
/// See [`compute_shell_warning_reason`] for the full list of reasons.
fn print_switch_message_if_changed(
changed_directory: bool,
main_path: &Path,
) -> anyhow::Result<()> {
if !changed_directory {
return Ok(());
}
// Use main_path for discovery - the worktree we came from may have been removed
let Ok(repo) = Repository::at(main_path) else {
return Ok(());
};
let Ok(Some(dest_branch)) = repo.worktree_at(main_path).branch() else {
return Ok(());
};
let logical_path = super::to_logical_path(main_path);
let path_display = format_path_for_display(&logical_path);
if super::is_shell_integration_active() {
// Shell integration active - cd will work
eprintln!(
"{}",
info_message(cformat!(
"Switched to worktree for <bold>{dest_branch}</> @ <bold>{path_display}</>"
))
);
} else if crate::is_git_subcommand() {
// Running as `git wt` - explain why cd can't work
eprintln!(
"{}",
warning_message(cformat!(
"Worktree for <bold>{dest_branch}</> @ <bold>{path_display}</>, but cannot change directory — ran git wt; running through git prevents cd"
))
);
eprintln!("{}", hint_message(git_subcommand_warning()));
} else {
// Shell integration not active - compute specific reason
let reason = compute_shell_warning_reason()?;
eprintln!(
"{}",
warning_message(cformat!(
"Worktree for <bold>{dest_branch}</> @ <bold>{path_display}</>, but cannot change directory — {reason}"
))
);
// Show appropriate hint based on invocation mode
if super::retired_shell_wrapper_active() {
super::print_outdated_shell_wrapper_hint_once();
} else if should_show_explicit_path_hint()? {
eprintln!("{}", hint_message(explicit_path_hint(&dest_branch)));
} else {
print_shell_activation_hint(&repo)?;
}
}
Ok(())
}
/// Compute the target directory for `cd` when moving the shell between
/// worktrees, preserving the user's subdirectory position when possible.
///
/// If the user is in `source_root/apps/gateway/` and `target_root/apps/gateway/`
/// exists, returns `target_root/apps/gateway/`. Otherwise returns `target_root`.
///
/// Shared by every command that relocates the shell — `switch`, `remove` (and
/// `merge`, which lands via the same handler), and `step relocate` — so they
/// preserve subdirectory position identically (canonicalizing to survive
/// symlinks, and falling back to the root when the subdir is absent).
pub(crate) fn resolve_subdir_in_target(
target_root: &Path,
source_root: Option<&Path>,
cwd: &Path,
) -> PathBuf {
if let Some(source_root) = source_root {
// Canonicalize both paths to handle symlinks (e.g., /var -> /private/var
// on macOS). Through `canonicalize_with_parents` rather than `dunce`
// directly, so a cwd past Windows' 260-character limit is spelled like
// the short worktree root containing it — otherwise `strip_prefix` below
// fails and the shell silently lands at the target root (#3898).
let cwd = canonicalize_with_parents(cwd);
let source_root = canonicalize_with_parents(source_root);
if let Ok(relative) = cwd.strip_prefix(&source_root)
&& !relative.as_os_str().is_empty()
{
let candidate = target_root.join(relative);
if candidate.is_dir() {
return candidate;
}
}
}
target_root.to_path_buf()
}
/// Where a switch's follow-on work runs, and which of those directories its
/// output should annotate with "@ path".
///
/// The `--execute` program always starts in the switch target — the worktree
/// root, or the subdirectory position [`resolve_subdir_in_target`] preserved —
/// so `execute_dir` is unconditional. The two `Option`s are the annotations,
/// `Some` only when the user's shell won't be where that work runs: background
/// hooks always run at the worktree root, and `--no-cd` leaves the shell behind
/// while the program still goes to the worktree (#4042).
pub struct SwitchDisplayPaths {
/// Where the background `post-switch` / `post-start` hooks run, when that
/// isn't where the user's shell is (or will be).
pub hooks: Option<PathBuf>,
/// Where the `--execute` program starts.
pub execute_dir: PathBuf,
/// [`Self::execute_dir`], when that isn't where the user's shell is (or
/// will be).
pub execute: Option<PathBuf>,
}
/// Handle output for a switch operation
///
/// # Shell Integration Warnings
///
/// Always warn when the shell's directory won't change. Users expect to be in
/// the target worktree after switching.
///
/// **When to warn:** Shell integration is not active (no directive files set).
/// This applies to both `Existing` and `Created` results.
///
/// **When NOT to warn:**
/// - `AlreadyAt` — user is already in the target directory
/// - Shell integration IS active — cd will happen automatically
///
/// **Warning format:** `Existing` shares the switch-to-existing shape,
/// `Worktree for X @ path, but cannot change directory — {reason}`; `Created`
/// warns with the bare `Cannot change directory — {reason}`, because the
/// success line printed above it already names the path.
///
/// See [`compute_shell_warning_reason`] for the full list of reasons.
///
/// **Message order for Created:** Success message first, then warning. Creation
/// is a real accomplishment, but users still need to know they won't cd there.
///
/// # Arguments
///
/// * `change_dir` — When false, skip the directory change (user requested `--no-cd`)
///
/// # Return Value
///
/// See [`SwitchDisplayPaths`] — the two annotations differ, because the hooks
/// and the `--execute` program don't always run in the same directory.
pub fn handle_switch_output(
result: &SwitchResult,
branch_info: &SwitchBranchInfo,
change_dir: bool,
source_worktree_root: Option<&Path>,
cwd: &Path,
) -> anyhow::Result<SwitchDisplayPaths> {
// Where the switch points, preserving subdirectory position: if the user is
// in apps/gateway/ in the source worktree and that directory exists in the
// target, that's apps/gateway/ in the target rather than its root. The
// `--execute` program starts there either way; `--no-cd` only declines to
// take the user's shell along.
let destination = resolve_subdir_in_target(result.path(), source_worktree_root, cwd);
if change_dir {
super::change_directory(&destination)?;
}
// Translate to the user's logical (symlink-preserved) path for display messages.
// The cd directive (above) handles its own translation internally.
let ctx = build_switch_output_context(result, branch_info, change_dir)?;
let display_path_for_hooks = match result {
SwitchResult::AlreadyAt(_) => handle_switch_already_at_output(&ctx),
SwitchResult::Existing { .. } => handle_switch_existing_output(&ctx)?,
SwitchResult::Created {
created_branch,
base_branch,
from_remote,
..
} => handle_switch_created_output(
&ctx,
*created_branch,
base_branch.as_deref(),
from_remote.as_deref(),
)?,
};
// The program runs in `destination`, which is the worktree root only when
// the user was at the source worktree's root: otherwise
// `resolve_subdir_in_target` kept their subdirectory position, and the
// hooks' path names a directory one level out from the program's. Annotate
// it only when the user's shell won't be there — it follows the program
// only when the switch cd'd and shell integration carried it (#4042).
let shell_follows = change_dir && super::is_shell_integration_active();
let display_path_for_execute = (!shell_follows)
.then(|| destination.clone())
.filter(|dir| super::global::compute_hooks_display_path(dir, cwd).is_some());
stderr().flush()?;
Ok(SwitchDisplayPaths {
hooks: display_path_for_hooks,
execute_dir: destination,
execute: display_path_for_execute.map(|dir| super::to_logical_path(&dir)),
})
}
/// Execute the --execute command after hooks have run.
///
/// The program runs in `dir` ([`SwitchDisplayPaths::execute_dir`]).
/// `display_path` is that same directory ([`SwitchDisplayPaths::execute`]), and
/// is `Some` only when the user's shell won't be there — otherwise the header
/// has nothing to annotate.
pub fn execute_user_command(
argv: &[String],
display_path: Option<&Path>,
dir: &Path,
redirect_stdout_to_stderr: bool,
) -> anyhow::Result<()> {
super::global::print_outdated_execute_wrapper_warning();
let command = super::global::format_exec_argv(argv);
// Show what command is being executed (section header + gutter content)
// Include path when user's shell won't be there (shell integration not active)
let header = match display_path {
Some(path) => {
let path_display = format_path_for_display(path);
cformat!("Executing (--execute) @ <bold>{path_display}</>:")
}
None => "Executing (--execute):".to_string(),
};
eprintln!("{}", progress_message(header));
eprintln!("{}", format_bash_with_gutter(&command));
super::execute(argv.to_vec(), dir, redirect_stdout_to_stderr)?;
Ok(())
}
/// Execute a [`RemovalPlan`] and narrate it per `execution`.
///
/// Returns the branch's [`BranchFate`] so callers report what happened rather
/// than what the plan intended — the prune summary and `--format=json` both
/// read it. Worktree-removal failures and hard branch-deletion failures
/// propagate as `Err`; an intentionally retained, unmerged, or moved branch
/// is a fate. Synchronous branch failures carry the worktree removal context,
/// including silent picker removal; detached fallback failures go to its log.
///
/// Approval is handled at the gate (command entry point), not here. The
/// `announcer`'s `show_branch` setting (set by the caller) controls whether
/// hook announce lines include the branch name for batch-context disambiguation.
/// When `quiet` is true (prune context), suppresses informational messages
/// like "No worktree found for branch X" that are noise in batch operations.
///
/// `hook_plan` is the frozen, approved hook set; an empty plan (`--no-hooks`,
/// declined, or no project config) runs no project hooks. `pre-remove` /
/// `post-remove` / `post-switch` execute only from it — the selection was
/// frozen at the gate, never re-read.
///
/// [`RemovalExecution::Silent`] (the TUI picker — this runs while skim owns
/// the terminal) removes a `Worktree` plan inline with no progress/success
/// messages, no trash-cleanup spinner, and no `cd` directive: just the git
/// removal plus the planned hooks. (The picker can't prompt mid-render, so its
/// `hook_plan` comes from a read-only `Approvals` filter — see `do_removal`.)
///
/// The [`BackgroundFallbackMode`] inside [`RemovalExecution::Background`]
/// selects how a removal whose rename-into-trash fast path fails behaves:
/// every caller but `wt step prune` passes
/// [`BackgroundFallbackMode::Detached`] (spawn the legacy `git worktree
/// remove`); prune passes [`BackgroundFallbackMode::SynchronousForNonCurrent`]
/// so a candidate's removal is complete by the time prune reports it removed.
pub fn handle_remove_output(
plan: &RemovalPlan,
execution: RemovalExecution,
stdin: ForegroundStdin,
hook_plan: &ApprovedHookPlan,
quiet: bool,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
handle_remove_output_inner(plan, execution, stdin, hook_plan, quiet, false, announcer)
}
/// Merge may select a source containing another checkout, including the
/// invoking worktree. Recheck its topology after pre-remove hooks, before the
/// removal core's final safety gates. This is merge-specific: ordinary remove
/// and batch prune retain their concurrent staging without a live registry
/// read before each rename.
pub fn handle_merge_remove_output(
plan: &RemovalPlan,
hook_plan: &ApprovedHookPlan,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
handle_remove_output_inner(
plan,
RemovalExecution::Background(BackgroundFallbackMode::Detached),
ForegroundStdin::Inherit,
hook_plan,
false,
true,
announcer,
)
}
fn handle_remove_output_inner(
plan: &RemovalPlan,
execution: RemovalExecution,
stdin: ForegroundStdin,
hook_plan: &ApprovedHookPlan,
quiet: bool,
protect_nested_worktrees: bool,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
match plan {
RemovalPlan::Worktree {
main_path,
worktree_path,
changed_directory,
branch_name,
deletion_mode,
target_branch,
integration_reason,
force_worktree,
removed_commit,
branch_checked_out_at,
} => handle_removed_worktree_output(
WorktreeRemovalContext {
main_path,
worktree_path,
changed_directory: *changed_directory,
branch_name: branch_name.as_deref(),
deletion_mode: *deletion_mode,
target_branch: target_branch.as_deref(),
integration_reason: *integration_reason,
force_worktree: *force_worktree,
removed_commit: removed_commit.as_deref(),
branch_checked_out_at: branch_checked_out_at.as_ref(),
hook_plan,
execution,
stdin,
protect_nested_worktrees,
},
announcer,
),
RemovalPlan::BranchOnly {
branch_name,
deletion_mode,
prune_entry,
target_branch,
integration_reason,
branch_checked_out_at,
detached_worktree,
} => handle_branch_only_output(
branch_name,
*deletion_mode,
prune_entry.as_deref(),
*integration_reason,
target_branch.as_deref(),
branch_checked_out_at.as_ref(),
detached_worktree.as_deref(),
quiet,
),
}
}
/// Handle output for BranchOnly removal (branch exists but no worktree)
///
/// `prune_entry` is the stale worktree entry the plan fell back from, if any;
/// it is unregistered here, first — unconditionally, unlike the branch
/// deletion the `should_keep`/CAS logic below may decline.
///
/// When `quiet` is true, suppresses the "No worktree found for branch X"
/// info line for non-pruned cases (noise in prune/batch context).
///
/// `detached_worktree` is a directory still sitting where this branch's
/// worktree would go, detached and so nameless in the branch namespace. The
/// removal is correct without it — the branch really has no worktree — but the
/// info line above reads as "nothing there", so it is named alongside, with the
/// path spelling that removes it. Only ever set for a branch the user typed.
///
/// The parameters are one `RemovalPlan::BranchOnly`'s fields, destructured by
/// the sole caller, plus `quiet` — so the count tracks the variant rather than
/// a signature anyone chose.
#[allow(clippy::too_many_arguments)]
fn handle_branch_only_output(
branch_name: &str,
deletion_mode: BranchDeletionMode,
prune_entry: Option<&Path>,
integration_reason: Option<IntegrationReason>,
target_branch: Option<&str>,
branch_checked_out_at: Option<&SharedBranchCheckout>,
detached_worktree: Option<&Path>,
quiet: bool,
) -> CommandResult<BranchFate> {
let pruned = if let Some(path) = prune_entry {
Repository::current()?.prune_worktree_entry(path)?;
true
} else {
false
};
// A stale registered entry and a detached worktree at the templated path
// can coexist. Name the detached directory even when pruning the entry.
let branch_info = if pruned {
success_message(cformat!("Pruned stale worktree for <bold>{branch_name}</>"))
} else if let Some(path) = detached_worktree {
let path = format_path_for_display(path);
info_message(cformat!(
"No worktree found for branch <bold>{branch_name}</>; a detached worktree is @ <bold>{path}</>"
))
} else {
info_message(cformat!(
"No worktree found for branch <bold>{branch_name}</>"
))
};
let announce_detached_worktree = || {
if let Some(path) = detached_worktree {
let path = format_path_for_display(path);
eprintln!(
"{}",
hint_message(cformat!(
"To remove the detached worktree, run <underline>wt remove {path}</>"
))
);
}
};
let announce_branch_info = || {
eprintln!("{branch_info}");
announce_detached_worktree();
};
// If we won't delete the branch, show info and return early
if deletion_mode.should_keep() {
announce_branch_info();
// A sibling `--force` checkout kept the branch alive; name it so the
// user knows why the pruned branch survived rather than being deleted.
if let Some(shared) = branch_checked_out_at {
print_branch_checked_out_elsewhere(branch_name, shared);
}
stderr()
.flush()
.map_err(|error| CommandFailure::with_result(error, BranchFate::NotAttempted))?;
return Ok(BranchFate::NotAttempted);
}
let check_target = target_branch.unwrap_or("HEAD");
// Force-delete bypasses integration and CAS. For safe-delete with a
// pre-computed integration reason, re-run deletion against fresh refs
// (`execute_branch_deletion`): the atomic CAS catches any tip movement
// since planning, rather than trusting the planner's stale view of the ref.
let deletion = if let Some(integrated_reason) = integration_reason
&& !deletion_mode.is_force()
{
let repo = worktrunk::git::Repository::current()?;
let result =
execute_branch_deletion(&repo, branch_name, check_target, false).map(|mut r| {
// Preserve the planner's recorded reason so a CAS-accepted
// delete still reports the original "integrated because X"
// explanation. The fresh integration target stays as the
// helper computed it.
if matches!(r.outcome, BranchDeletionOutcome::Integrated(_)) {
r.outcome = BranchDeletionOutcome::Integrated(integrated_reason);
}
r
});
handle_branch_deletion_result(result, branch_name).map_err(|error| {
CommandFailure::with_result(error, BranchFate::Retained(RetainedReason::Failed))
})?
} else if deletion_mode.is_force() {
let repo = worktrunk::git::Repository::current()?;
let result = execute_branch_deletion(&repo, branch_name, check_target, true);
handle_branch_deletion_result(result, branch_name).map_err(|error| {
CommandFailure::with_result(error, BranchFate::Retained(RetainedReason::Failed))
})?
} else {
BranchDeletionDisplay {
result: BranchDeletionResult {
outcome: BranchDeletionOutcome::NotDeleted,
integration_target: check_target.to_string(),
},
show_unmerged_hint: true,
}
};
let retained = match &deletion.result.outcome {
BranchDeletionOutcome::RetainedCheckedOut { path } => {
announce_branch_info();
eprintln!(
"{}",
retained_checked_out_branch_message(branch_name, path, false)
);
true
}
BranchDeletionOutcome::RetainedRaced => {
announce_branch_info();
eprintln!("{}", retained_raced_branch_message(branch_name, false));
true
}
BranchDeletionOutcome::NotDeleted => {
announce_branch_info();
if deletion.show_unmerged_hint {
print_retained_unmerged_branch(branch_name);
}
true
}
BranchDeletionOutcome::Integrated(_) | BranchDeletionOutcome::ForceDeleted => false,
};
if !retained {
let flag_note = flag_note(
deletion_mode,
&deletion.result.outcome,
Some(&deletion.result.integration_target),
);
let flag_text = &flag_note.text;
let flag_after = flag_note.after(AnsiColor::Green);
if pruned {
// Combined: pruned stale metadata & deleted branch in one line
eprintln!(
"{}",
FormattedMessage::new(cformat!(
"<green>✓ Pruned stale worktree & removed branch <bold>{branch_name}</>{flag_text}</>{flag_after}"
))
);
announce_detached_worktree();
} else {
if !quiet {
announce_branch_info();
}
eprintln!(
"{}",
FormattedMessage::new(cformat!(
"<green>✓ Removed branch <bold>{branch_name}</>{flag_text}</>{flag_after}"
))
);
}
}
let fate = BranchFate::from_outcome(&deletion.result.outcome);
stderr()
.flush()
.map_err(|error| CommandFailure::with_result(error, fate))?;
Ok(fate)
}
/// Register post-remove and post-switch hooks after worktree removal onto the
/// caller's announcer.
///
/// Pipelines come from two contexts: post-remove uses the removed worktree's
/// identity (branch, path, commit), while post-switch (only when
/// `changed_directory` is true) uses the destination worktree's branch. Both
/// types share whatever announce line the caller's announcer eventually
/// flushes — multi-phase callers (e.g. `wt merge`) batch with later phases,
/// standalone callers (e.g. `wt remove`) flush immediately after.
///
/// Hook selection is the frozen `ctx.hook_plan`, so an empty plan
/// (`--no-hooks`, declined approval, or no project config) registers nothing.
/// The removed-worktree mark below is not part of that: it records what the
/// removal did, which no approval decision changes.
fn spawn_hooks_after_remove(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
removed_branch: Option<&str>,
announcer: &mut HookAnnouncer<'_>,
) -> anyhow::Result<()> {
// The worktree is gone (or, on the fallback path, being deleted by the
// detached `git worktree remove` this call follows), so a pipeline anchored
// on it must not be spawned into it.
announcer.mark_worktree_removed(ctx.worktree_path);
// The startup snapshot, not a reload: `pre-remove` and the removal itself
// may have rewritten the user config since the approval gate read it.
let config = repo.user_config();
// When removing the current worktree, user cd's to main_path → use post_hook logic
// (suppresses path if shell integration will cd there).
// When removing a different worktree, user stays at cwd → use pre_hook logic
// (shows path if main_path differs from cwd).
let display_path = if ctx.changed_directory {
super::post_hook_display_path(ctx.main_path)
} else {
super::pre_hook_display_path(ctx.main_path)
};
// Build post-remove template variables from the removed worktree identity.
let remove_vars =
PostRemoveContext::new(ctx.worktree_path, ctx.removed_commit, ctx.main_path, repo);
let extra_vars = remove_vars.extra_vars(removed_branch);
// All hooks use remove_ctx for spawning: log files are named after the removed
// branch since both post-remove and post-switch are consequences of that removal.
let remove_ctx = CommandContext::new(repo, config, removed_branch, ctx.main_path, false);
// `post-remove` is *about* the removed worktree (gone by now); it was
// selected and frozen into `hook_plan` at the gate, anchored at the removed
// worktree path. `remove_ctx` (rooted at `ctx.main_path`) only renders.
register_planned(
announcer,
ctx.hook_plan,
ctx.worktree_path,
&remove_ctx,
worktrunk::HookType::PostRemove,
&extra_vars,
display_path,
)?;
// Post-switch: only when the user actually changed directory. Anchored at
// the destination worktree (where the user landed) at the gate.
if ctx.changed_directory {
let dest_branch = repo.worktree_at(ctx.main_path).branch()?;
let switch_ctx =
CommandContext::new(repo, config, dest_branch.as_deref(), ctx.main_path, false);
register_planned(
announcer,
ctx.hook_plan,
ctx.main_path,
&switch_ctx,
worktrunk::HookType::PostSwitch,
&[],
display_path,
)?;
}
Ok(())
}
// ============================================================================
// Removal Display Info: Shared data for background/foreground output
// ============================================================================
/// Information needed to display removal messages and hints.
///
/// This struct captures the outcome of a branch deletion decision (freshly
/// computed for background mode or actual for foreground mode) so that message
/// formatting can be shared between both modes.
struct RemovalDisplayInfo {
/// The observed deletion outcome, including retained race cases.
outcome: BranchDeletionOutcome,
/// The target branch used for integration check (may be upstream if ahead of local)
integration_target: Option<String>,
/// Whether the branch was integrated (used for hints when branch is kept)
branch_was_integrated: bool,
/// Whether to show the "unmerged, run -D" hint (foreground only, based on actual deletion)
show_unmerged_hint: bool,
/// Whether --force was used (for display purposes)
force_worktree: bool,
}
impl RemovalDisplayInfo {
/// Build display info from the refreshed integration check (background mode).
///
/// The caller refreshes this after `pre-remove` hooks and immediately
/// before staging/removing the worktree.
fn from_precomputed(
deletion_mode: BranchDeletionMode,
pre_computed_integration: Option<IntegrationReason>,
target_branch: Option<&str>,
force_worktree: bool,
) -> Self {
let (outcome, integration_target) = if deletion_mode.should_keep() {
(
BranchDeletionOutcome::NotDeleted,
target_branch.map(String::from),
)
} else if deletion_mode.is_force() {
(
BranchDeletionOutcome::ForceDeleted,
target_branch.map(String::from),
)
} else {
let outcome = match pre_computed_integration {
Some(r) => BranchDeletionOutcome::Integrated(r),
None => BranchDeletionOutcome::NotDeleted,
};
(outcome, target_branch.map(String::from))
};
Self {
outcome,
integration_target,
branch_was_integrated: pre_computed_integration.is_some(),
show_unmerged_hint: false, // Background mode never shows this hint
force_worktree,
}
}
/// Build display info from actual deletion result (foreground mode).
fn from_branch_result(
branch_deletion: Option<BranchDeletionResult>,
pre_computed_integration: Option<IntegrationReason>,
target_branch: Option<&str>,
force_worktree: bool,
) -> Self {
let branch_was_integrated = pre_computed_integration.is_some();
let (outcome, integration_target, show_unmerged_hint) = match branch_deletion {
Some(result) => {
// Only display a real target, not the "HEAD" fallback.
let display_target = target_branch.map(|_| result.integration_target);
let show_unmerged_hint =
matches!(result.outcome, BranchDeletionOutcome::NotDeleted);
(result.outcome, display_target, show_unmerged_hint)
}
None => (
BranchDeletionOutcome::NotDeleted,
target_branch.map(String::from),
false,
),
};
Self {
outcome,
integration_target,
branch_was_integrated,
show_unmerged_hint,
force_worktree,
}
}
/// Whether the branch will be/was deleted.
fn branch_deleted(&self) -> bool {
matches!(
self.outcome,
BranchDeletionOutcome::ForceDeleted | BranchDeletionOutcome::Integrated(_)
)
}
/// Print the removal message (progress for background, success for foreground).
///
/// `stats` carries the trash-cleanup file/byte counts surfaced by the
/// foreground spinner (see `remove_dir_with_progress`). Pass `None` for
/// the background path — those don't run a spinner and shouldn't show
/// stats. The `(N files · X MiB)` suffix is gray, matching the
/// "stats parentheses" convention in the user-output skill.
fn print_message(
&self,
branch_name: &str,
foreground: bool,
stats: Option<(usize, u64)>,
) -> anyhow::Result<()> {
let flag_note = flag_note(
if self.branch_deleted() {
BranchDeletionMode::SafeDelete // Doesn't matter, outcome already determined
} else {
BranchDeletionMode::Keep
},
&self.outcome,
self.integration_target.as_deref(),
);
let force_text = if self.force_worktree {
" (--force)"
} else {
""
};
let stats_paren = stats
.map(|(f, b)| format_stats_paren(f, b))
.unwrap_or_default();
let msg = if foreground {
if self.branch_deleted() {
let flag_text = &flag_note.text;
success_message(cformat!(
"Removed <bold>{branch_name}</> worktree{force_text} & branch{flag_text}"
))
.append(&flag_note.after(AnsiColor::Green))
.append(&stats_paren)
} else {
success_message(cformat!(
"Removed <bold>{branch_name}</> worktree{force_text}"
))
.append(&stats_paren)
}
} else if self.branch_deleted() {
let flag_text = &flag_note.text;
progress_message(cformat!(
"Removing <bold>{branch_name}</> worktree{force_text} & branch in background{flag_text}"
))
.append(&flag_note.after(AnsiColor::Cyan))
} else {
progress_message(cformat!(
"Removing <bold>{branch_name}</> worktree{force_text} in background"
))
};
eprintln!("{msg}");
Ok(())
}
/// Print hints about branch status (why it was kept, how to force delete).
fn print_hints(
&self,
branch_name: &str,
deletion_mode: BranchDeletionMode,
pre_computed_integration: Option<IntegrationReason>,
) -> anyhow::Result<()> {
if self.branch_deleted() {
return Ok(());
}
// A raced retention isn't "unmerged" — the branch was integrated but
// either gained a checkout or its tip moved during the delete. Surface
// the dedicated message rather than falling through to the generic
// unmerged hint, whose explanation would be false.
match &self.outcome {
BranchDeletionOutcome::RetainedCheckedOut { path } => {
eprintln!(
"{}",
retained_checked_out_branch_message(branch_name, path, true)
);
return Ok(());
}
BranchDeletionOutcome::RetainedRaced => {
eprintln!("{}", retained_raced_branch_message(branch_name, true));
return Ok(());
}
BranchDeletionOutcome::NotDeleted
| BranchDeletionOutcome::ForceDeleted
| BranchDeletionOutcome::Integrated(_) => {}
}
if deletion_mode.should_keep() {
if let Some(reason) = pre_computed_integration.as_ref() {
// User kept an integrated branch - show integration info
let target = self.integration_target.as_deref().unwrap_or("target");
let desc = reason.description();
let symbol = reason.symbol();
eprintln!(
"{}",
hint_message(cformat!(
"Branch integrated ({desc} <underline>{target}</>, <dim>{symbol}</>); retained with <underline>--no-delete-branch</>"
))
);
}
} else if self.show_unmerged_hint
|| (!deletion_mode.should_keep() && !self.branch_was_integrated)
{
// Unmerged, no flag - show how to force delete
// (Background: !should_keep && !integrated, Foreground: show_unmerged_hint)
let cmd = suggest_command("remove", &[branch_name], &["-D"]);
eprintln!(
"{}",
hint_message(cformat!(
"Branch unmerged; to delete, run <underline>{cmd}</>"
))
);
}
// else: Unmerged + flag - no hint (flag had no effect)
Ok(())
}
}
// ============================================================================
struct WorktreeRemovalContext<'a> {
main_path: &'a Path,
worktree_path: &'a Path,
changed_directory: bool,
branch_name: Option<&'a str>,
deletion_mode: BranchDeletionMode,
target_branch: Option<&'a str>,
/// Planning-time integration verdict (display and retention prediction
/// only — the deletion re-decides via `delete_branch_if_safe`'s CAS).
integration_reason: Option<IntegrationReason>,
force_worktree: bool,
removed_commit: Option<&'a str>,
/// A surviving checkout of this branch, when one exists. `Some` means the
/// branch was retained rather than deleted; see [`SharedBranchCheckout`].
branch_checked_out_at: Option<&'a SharedBranchCheckout>,
/// The frozen, approved hook plan. `pre-remove` / `post-remove` /
/// `post-switch` execute only from this — no `.config/wt.toml` re-read,
/// no `ProjectConfig` snapshot to thread.
hook_plan: &'a ApprovedHookPlan,
execution: RemovalExecution,
stdin: ForegroundStdin,
protect_nested_worktrees: bool,
}
impl WorktreeRemovalContext<'_> {
/// The fallback mode for a background removal. Only the background paths
/// consult this; they are reached only via [`RemovalExecution::Background`],
/// so the other arms default to the standard detached fallback rather than
/// carrying an unreachable panic in the removal path.
fn background_fallback(&self) -> BackgroundFallbackMode {
match self.execution {
RemovalExecution::Background(mode) => mode,
RemovalExecution::Foreground | RemovalExecution::Silent => {
BackgroundFallbackMode::Detached
}
}
}
}
fn execute_pre_remove_hooks_if_needed(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
) -> anyhow::Result<()> {
// `pre-remove` runs in the worktree being removed (still on disk here).
// `pre_remove_repo` roots the *render* context there for template vars;
// the command set is the frozen `hook_plan` selected at the gate, so no
// `.config/wt.toml` is re-read here.
let pre_remove_repo = Repository::at(ctx.worktree_path)?;
let command_ctx = CommandContext::new(
&pre_remove_repo,
pre_remove_repo.user_config(),
ctx.branch_name,
ctx.worktree_path,
false, // yes=false for CommandContext (not approval-related)
)
.with_stdin(ctx.stdin);
let display_path = if ctx.changed_directory {
None
} else {
Some(ctx.worktree_path)
};
// `TemplateVars` rather than a hand-rolled vec: `as_extra_vars` omits an
// absent `target` instead of pushing `""`, so a detached primary worktree
// renders the same here as it does for the `post-remove` half of the same
// removal (issue #4009).
let target_branch = repo.worktree_at(ctx.main_path).branch().ok().flatten();
let vars = TemplateVars::new()
.with_target_opt(target_branch.as_deref())
.with_target_worktree_path(ctx.main_path);
let extra_vars = vars.as_extra_vars();
execute_planned_hook(
ctx.hook_plan,
ctx.worktree_path,
&command_ctx,
worktrunk::HookType::PreRemove,
&extra_vars,
FailureStrategy::FailFast,
display_path,
)
}
fn prepare_remove_directory_change(
main_path: &Path,
worktree_path: &Path,
changed_directory: bool,
) -> anyhow::Result<()> {
if changed_directory {
// Preserve the user's subdirectory position, mirroring `wt switch`
// (#3343). The removal hasn't run yet, so the current directory still
// exists inside the worktree being removed — if the user is in
// `worktree/apps/gateway/` and `main/apps/gateway/` exists, cd there
// instead of the main worktree root. Falls back to the root when the
// subdir is absent in the destination or the cwd can't be read.
// `shell_cwd()` rather than the process cwd, so the preservation
// survives a `wt remove` nested in an alias or hook body, whose
// process cwd is the worktree root (#3723).
let cd_target = shell_cwd()
.map(|cwd| resolve_subdir_in_target(main_path, Some(worktree_path), &cwd))
.unwrap_or_else(|| main_path.to_path_buf());
super::change_directory(&cd_target)?;
stderr().flush()?; // Force flush to ensure shell processes the cd
// Mark that the CWD worktree is being removed, so the error handler
// can show a hint if a subsequent command (e.g., post-merge hook) fails.
super::mark_cwd_removed();
}
Ok(())
}
fn handle_detached_removed_worktree_output(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
let fate = if matches!(ctx.execution, RemovalExecution::Foreground) {
eprintln!(
"{}",
progress_message(cformat!(
"Removing worktree @ <bold>{}</>... (detached HEAD, no branch to delete)",
format_path_for_display(ctx.worktree_path)
))
);
let snapshot = repo.capture_refs()?;
let output = remove_worktree_with_cleanup(
repo,
&snapshot,
ctx.worktree_path,
RemoveOptions {
branch: None,
deletion_mode: ctx.deletion_mode,
target_branch: ctx.target_branch.map(String::from),
force_worktree: ctx.force_worktree,
},
)?;
let (files, bytes) = output
.staged_path
.as_deref()
.map(cleanup_staged_with_progress)
.unwrap_or((0, 0));
let stats_paren = format_stats_paren(files, bytes);
eprintln!(
"{}",
success_message(cformat!(
"Removed worktree @ <bold>{}</> (detached HEAD, no branch to delete)",
format_path_for_display(ctx.worktree_path)
))
.append(&stats_paren)
);
Ok(BranchFate::NotAttempted)
} else {
let path_display = format_path_for_display(ctx.worktree_path);
eprintln!(
"{}",
progress_message(cformat!(
"Removing worktree @ <bold>{path_display}</> in background (detached HEAD, no branch to delete)"
))
);
spawn_background_removal(
repo,
ctx.main_path,
&BackgroundRemoval {
worktree_path: ctx.worktree_path,
branch_name: None,
deletion_mode: ctx.deletion_mode,
target_branch: ctx.target_branch,
force_worktree: ctx.force_worktree,
changed_directory: ctx.changed_directory,
// No branch → field is unused, but pick the silent-on-NotDeleted
// default in case the detached HEAD ever gains a branch name.
planner_expected_retention: true,
},
"detached",
ctx.background_fallback(),
)
};
// A detached worktree was on no branch, so `{{ branch }}` stays unset for
// the post-remove hooks (issue #4009).
if let Err(failure) = &fate
&& failure.result.is_none()
{
return fate;
}
let finish = spawn_hooks_after_remove(repo, ctx, None, announcer)
.and_then(|()| stderr().flush().map_err(Into::into));
fate.and_then(|fate| {
finish
.map(|()| fate)
.map_err(|error| CommandFailure::with_result(error, fate))
})
}
fn handle_named_removed_worktree_foreground(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
branch_name: &str,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
eprintln!(
"{}",
progress_message(cformat!("Removing <bold>{branch_name}</> worktree..."))
);
let snapshot = repo.capture_refs()?;
let output = remove_worktree_with_cleanup(
repo,
&snapshot,
ctx.worktree_path,
RemoveOptions {
branch: Some(branch_name.to_string()),
deletion_mode: ctx.deletion_mode,
target_branch: ctx.target_branch.map(String::from),
force_worktree: ctx.force_worktree,
},
)?;
let stats = output
.staged_path
.as_deref()
.map(cleanup_staged_with_progress)
.unwrap_or((0, 0));
// The worktree is gone even when branch deletion or hook setup failed.
let fate = BranchFate::from_result(output.branch_result.as_ref());
let finish = (|| -> anyhow::Result<()> {
spawn_hooks_after_remove(repo, ctx, Some(branch_name), announcer)?;
let branch_result = output.branch_result.transpose()?;
let display_info = RemovalDisplayInfo::from_branch_result(
branch_result,
ctx.integration_reason,
ctx.target_branch,
ctx.force_worktree,
);
display_info.print_message(branch_name, true, Some(stats))?;
display_info.print_hints(branch_name, ctx.deletion_mode, ctx.integration_reason)?;
if let Some(shared) = ctx.branch_checked_out_at {
print_branch_checked_out_elsewhere(branch_name, shared);
}
print_switch_message_if_changed(ctx.changed_directory, ctx.main_path)?;
stderr().flush()?;
Ok(())
})();
finish
.map(|()| fate)
.map_err(|error| CommandFailure::with_result(error, fate))
}
fn handle_named_removed_worktree_background(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
branch_name: &str,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
let display_info = RemovalDisplayInfo::from_precomputed(
ctx.deletion_mode,
ctx.integration_reason,
ctx.target_branch,
ctx.force_worktree,
);
display_info.print_message(branch_name, false, None)?;
display_info.print_hints(branch_name, ctx.deletion_mode, ctx.integration_reason)?;
if let Some(shared) = ctx.branch_checked_out_at {
print_branch_checked_out_elsewhere(branch_name, shared);
}
print_switch_message_if_changed(ctx.changed_directory, ctx.main_path)?;
// Planner predicted retention when the user asked to keep, or when the
// integration check at planning time returned no reason — `print_hints`
// has already explained either case. A `NotDeleted` outcome surprises only
// if the planner predicted deletion.
let planner_expected_retention =
ctx.deletion_mode.should_keep() || ctx.integration_reason.is_none();
let fate = spawn_background_removal(
repo,
ctx.main_path,
&BackgroundRemoval {
worktree_path: ctx.worktree_path,
branch_name: Some(branch_name),
deletion_mode: ctx.deletion_mode,
target_branch: ctx.target_branch,
force_worktree: ctx.force_worktree,
changed_directory: ctx.changed_directory,
planner_expected_retention,
},
branch_name,
ctx.background_fallback(),
);
// No removal took place on an early error, so there is no teardown to run.
if let Err(failure) = &fate
&& failure.result.is_none()
{
return fate;
}
let finish = spawn_hooks_after_remove(repo, ctx, Some(branch_name), announcer)
.and_then(|()| stderr().flush().map_err(Into::into));
fate.and_then(|fate| {
finish
.map(|()| fate)
.map_err(|error| CommandFailure::with_result(error, fate))
})
}
/// Execute and narrate a [`RemovalPlan::Worktree`] plan.
fn handle_removed_worktree_output(
ctx: WorktreeRemovalContext<'_>,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
// Use main_path for discovery - the worktree being removed might be cwd,
// and git operations after removal need a valid working directory.
let repo = worktrunk::git::Repository::at(ctx.main_path)?;
if ctx
.hook_plan
.has_hooks_for(ctx.worktree_path, &[worktrunk::HookType::PreRemove])
{
execute_pre_remove_hooks_if_needed(&repo, &ctx)?;
}
// This read may wait for a registry teardown. Keep it before the final
// ownership/lock/dirty gates in the removal core, so edits made during
// the wait are checked before staging. Also precede the cd directive:
// refusing cleanup must not move the invoking shell.
if ctx.protect_nested_worktrees
&& let Some(nested) = worktrunk::git::remove::nested_worktree(&repo, ctx.worktree_path)?
{
return Err(anyhow::anyhow!(cformat!(
"Cannot remove worktree @ <bold>{}</>; contains worktree @ <bold>{}</>",
format_path_for_display(ctx.worktree_path),
format_path_for_display(&nested)
))
.into());
}
// The pre-rename `ensure_clean` catches a hook-dirtied worktree, and the
// branch deletion re-decides against fresh refs (`delete_branch_if_safe`'s
// CAS). The planning-time integration verdict is only for display.
// TUI (picker) path: the removal runs in a background thread while skim
// owns the terminal, so no messages, no spinner, no `cd` directive (the
// picker manages its own cwd). The git removal runs inline — same as the
// foreground path, minus the chrome.
if matches!(ctx.execution, RemovalExecution::Silent) {
return remove_removed_worktree_silently(&repo, &ctx, announcer);
}
// `--force` already consents to losing what the worktree holds.
let local_submodules = if ctx.force_worktree {
Vec::new()
} else {
repo.worktree_at(ctx.worktree_path)
.submodules_with_local_commits()?
};
for submodule in local_submodules {
eprintln!(
"{}",
warning_message(cformat!(
"Submodule <bold>{submodule}</> has commits on no remote; removing the worktree deletes them"
))
);
}
prepare_remove_directory_change(ctx.main_path, ctx.worktree_path, ctx.changed_directory)?;
// Handle detached HEAD case (no branch known)
let Some(branch_name) = ctx.branch_name else {
return handle_detached_removed_worktree_output(&repo, &ctx, announcer);
};
if matches!(ctx.execution, RemovalExecution::Foreground) {
handle_named_removed_worktree_foreground(&repo, &ctx, branch_name, announcer)
} else {
handle_named_removed_worktree_background(&repo, &ctx, branch_name, announcer)
}
}
/// Remove a [`RemovalPlan::Worktree`] target with no terminal output — the
/// TUI (`wt switch` picker) path of [`handle_remove_output`].
///
/// `pre-remove` has already run (when it was approved — `verify`), and the
/// caller skipped the `cd` directive (the picker manages its own process cwd).
/// This does the synchronous git worktree removal and registers `post-remove` /
/// `post-switch` hooks onto `announcer`, but with no progress/success message
/// and no trash-cleanup spinner — `eprintln!` while skim owns the terminal
/// would corrupt the frame. Removal failures propagate to the picker.
fn remove_removed_worktree_silently(
repo: &Repository,
ctx: &WorktreeRemovalContext<'_>,
announcer: &mut HookAnnouncer<'_>,
) -> CommandResult<BranchFate> {
let snapshot = repo.capture_refs()?;
let options = RemoveOptions {
branch: ctx.branch_name.map(String::from),
deletion_mode: ctx.deletion_mode,
target_branch: ctx.target_branch.map(String::from),
force_worktree: ctx.force_worktree,
};
let output = remove_worktree_with_cleanup(repo, &snapshot, ctx.worktree_path, options)?;
if let Some(staged) = output.staged_path {
// Best-effort, same as the fast-path cleanup in the foreground handler
// but without the TTY spinner (`cleanup_staged_with_progress`).
let _ = std::fs::remove_dir_all(&staged);
}
// Post-remove (and post-switch when the picker cd'd away) hooks — registered
// onto the caller's announcer, which `flush`es after this returns.
let fate = BranchFate::from_result(output.branch_result.as_ref());
spawn_hooks_after_remove(repo, ctx, ctx.branch_name, announcer)
.map_err(|error| CommandFailure::with_result(error, fate))?;
output
.branch_result
.transpose()
.map_err(|error| CommandFailure::with_result(error, fate))?;
Ok(fate)
}
/// Run a shell command with streaming output, signal forwarding, and ANSI reset.
///
/// Entry point for foreground hook and alias execution. `wt step for-each`
/// (`for_each.rs`, direct argv exec with no shell) and the background
/// pipeline runner (`run_pipeline.rs`, redirects to log files and runs
/// detached) have their own spawning logic.
///
/// Capabilities: optional stdout→stderr redirect for deterministic ordering,
/// native Ctrl-C and direct-child SIGTERM delivery, ANSI reset before child
/// runs, `Cmd` tracing/logging, and CD directive control.
///
/// ## Stdin
///
/// Exclusive pipelines inherit stdin. Picker removals and parallel prune hooks
/// close it so they cannot consume another input owner's bytes. Process-group
/// membership and signal forwarding are independent of this input policy.
/// Hook context comes from template variables.
///
/// ## Directive files
///
/// `directives` controls whether the child can write shell-integration
/// directives back to the parent shell. The CD file holds a raw path and is
/// safe to pass through.
///
/// - `DirectivePassthrough::default()` — scrubs all directive env vars from
/// the child. Used by background hooks (outlive the parent shell).
/// - `DirectivePassthrough::inherit_from_env()` — re-adds CD. Used by aliases
/// and foreground hooks, which may emit `cd` directives.
///
/// ## Stdout routing
///
/// `redirect_stdout_to_stderr` controls whether the child's stdout is merged
/// onto wt's stderr (`true`) or passed through unchanged (`false`).
///
/// - Hooks pass `true`: their output is decoration around
/// wt's own stderr messages, and merging keeps "Running …" / progress lines
/// ordered with the child's own writes.
/// - Aliases pass `false`: `wt <alias>` is a user-defined command and its
/// stdout must remain pipeable, so `wt my-alias | jq` and similar
/// compositions work (#2478).
///
/// ## ANSI reset
///
/// Resets ANSI codes on stderr before the child runs. Terminal emulators
/// maintain a single rendering state machine — if stdout writes color codes
/// but stderr's output arrives next, the terminal applies stdout's color
/// state to stderr's text. The reset to stderr prevents this.
///
/// ## Git discovery
///
/// `scrub_git_discovery` removes inherited `GIT_DIR`/`GIT_WORK_TREE` (and the
/// rest of [`INHERITED_GIT_PATH_VARS`]) from the child so its `git` commands
/// discover the repo from `working_dir`. Hooks pass `true` (they operate on the
/// worktree wt targets); aliases pass `false` (they keep wt's inherited context,
/// like a top-level command the user typed). See issue #3373.
///
/// [`INHERITED_GIT_PATH_VARS`]: worktrunk::shell_exec::INHERITED_GIT_PATH_VARS
pub fn execute_shell_command(
working_dir: &std::path::Path,
command: &str,
command_log_label: Option<&str>,
directives: DirectivePassthrough,
stdin: ForegroundStdin,
redirect_stdout_to_stderr: bool,
scrub_git_discovery: bool,
) -> anyhow::Result<()> {
// Flush stdout before executing command to ensure all our messages appear
// before the child process output
stderr().flush()?;
// Reset ANSI codes on stderr to prevent color bleeding (see function docs for details)
// This fixes color bleeding observed when worktrunk prints colored output to stdout
// followed immediately by child process output to stderr (e.g., pre-commit run output).
eprint!("{}", anstyle::Reset);
stderr().flush().ok(); // Ignore flush errors - reset is best-effort, command execution should proceed
let mut cmd = Cmd::shell(command).current_dir(working_dir);
// User hooks discover their repo from the cwd wt sets, not an inherited
// GIT_DIR/GIT_WORK_TREE (issue #3373). Aliases keep the inherited context.
if scrub_git_discovery {
cmd = cmd.scrub_git_discovery_env();
}
if redirect_stdout_to_stderr {
cmd = cmd.stdout(Stdio::from(std::io::stderr()));
}
if let Some(label) = command_log_label {
cmd = cmd.external(label);
}
cmd = match stdin {
ForegroundStdin::Inherit => cmd.inherit_stdin().forward_signals(),
ForegroundStdin::HandOff => cmd.inherit_stdin().hand_off_terminal(),
ForegroundStdin::Closed => cmd.stdin(Stdio::null()).forward_signals(),
};
if let Some(path) = directives.cd_file {
cmd = cmd.directive_cd_file(path);
}
cmd.stream()?;
// Flush to ensure all output appears before we continue
stderr().flush()?;
Ok(())
}
/// Selector for which directive file env vars to pass through to a child shell.
///
/// `Default` (no fields set) scrubs all directive env vars from the child;
/// [`DirectivePassthrough::inherit_from_env`] reads the current process
/// environment and re-adds CD.
#[derive(Debug, Default, Clone)]
pub struct DirectivePassthrough {
pub cd_file: Option<std::path::PathBuf>,
}
impl DirectivePassthrough {
/// Pass the CD directive file through to the child, reading the current
/// process environment. Used by project aliases and foreground hooks that
/// may legitimately emit a `cd` directive.
pub fn inherit_from_env() -> Self {
use worktrunk::shell_exec::DIRECTIVE_CD_FILE_ENV_VAR;
Self {
cd_file: read_directive_env(DIRECTIVE_CD_FILE_ENV_VAR),
}
}
}
fn read_directive_env(var: &str) -> Option<std::path::PathBuf> {
std::env::var_os(var)
.map(std::path::PathBuf::from)
.filter(|p| !p.as_os_str().is_empty())
}
#[cfg(test)]
mod tests {
use super::*;
use insta::assert_snapshot;
/// Silent removal reports a hard ref failure after removing the checkout.
#[test]
fn silent_branch_failure_preserves_removal_context() {
use crate::commands::repository_ext::{RemoveTarget, RepositoryCliExt};
let mut test = worktrunk::testing::TestRepo::with_initial_commit();
let path = test.add_worktree("feature");
let repo = Repository::at(test.path()).unwrap();
let plan = repo
.prepare_worktree_removal(
RemoveTarget::WorktreePath(path.clone()),
BranchDeletionMode::SafeDelete,
false,
test.path(),
None,
None,
)
.unwrap();
std::fs::write(
repo.git_common_dir().join("refs/heads/feature.lock"),
"another writer",
)
.unwrap();
let mut announcer = HookAnnouncer::new(&repo, false);
let error = handle_remove_output(
&plan,
RemovalExecution::Silent,
ForegroundStdin::Inherit,
&ApprovedHookPlan::empty(),
true,
&mut announcer,
)
.unwrap_err();
assert_eq!(
error.result.as_deref(),
Some(&BranchFate::Retained(RetainedReason::Failed))
);
assert!(matches!(
error.error.downcast_ref::<GitError>(),
Some(GitError::BranchDeletionFailed { branch, removed_worktree: Some(removed), .. })
if branch == "feature" && removed == &path
));
assert!(!path.exists());
assert!(repo.branch("feature").exists_locally().unwrap());
}
/// Exercises each arm of [`warn_if_branch_retained`] for coverage and
/// to pin the suppression rule. Output goes to stderr and isn't captured
/// here — the assertion is that the call doesn't panic on any arm.
/// User-visible message shapes are exercised by the integration tests
/// (e.g. `test_merge_pre_remove_new_commit_keeps_branch`).
#[test]
fn warn_if_branch_retained_arms() {
let ok = |outcome| {
Ok::<_, anyhow::Error>(BranchDeletionResult {
outcome,
integration_target: "main".to_string(),
})
};
// NotDeleted + planner did NOT expect retention → warn (surprise race)
warn_if_branch_retained("feature", &ok(BranchDeletionOutcome::NotDeleted), false);
// NotDeleted + planner DID expect retention → silent (print_hints
// already explained)
warn_if_branch_retained("feature", &ok(BranchDeletionOutcome::NotDeleted), true);
// RetainedRaced → always surface, regardless of planner prediction
warn_if_branch_retained("feature", &ok(BranchDeletionOutcome::RetainedRaced), false);
warn_if_branch_retained("feature", &ok(BranchDeletionOutcome::RetainedRaced), true);
// RetainedCheckedOut → surface the checkout path
warn_if_branch_retained(
"feature",
&ok(BranchDeletionOutcome::RetainedCheckedOut {
path: Path::new("/tmp/repo.feature-survivor").to_path_buf(),
}),
false,
);
// Success arms → silent
warn_if_branch_retained("feature", &ok(BranchDeletionOutcome::ForceDeleted), false);
warn_if_branch_retained(
"feature",
&ok(BranchDeletionOutcome::Integrated(
IntegrationReason::SameCommit,
)),
false,
);
// Err arm → caller propagates it after arranging trash cleanup.
warn_if_branch_retained(
"feature",
&Err(anyhow::anyhow!("simulated git failure")),
false,
);
}
/// The shared raced-retention message varies its lead-in with
/// `removed_worktree` and always suggests the canonical `-D` recovery.
#[test]
fn retained_raced_branch_message_lead_in_varies() {
let removed = retained_raced_branch_message("feature", true);
assert!(removed.contains("Removed worktree but kept branch"));
assert!(removed.contains("moved during deletion"));
assert!(removed.contains("wt remove -D feature"));
let branch_only = retained_raced_branch_message("feature", false);
assert!(branch_only.contains("Kept branch"));
assert!(!branch_only.contains("Removed worktree"));
assert!(branch_only.contains("wt remove -D feature"));
}
#[test]
fn retained_checked_out_branch_message_names_checkout() {
let path = Path::new("/tmp/repo.feature-survivor");
let removed = retained_checked_out_branch_message("feature", path, true);
assert!(removed.contains("Removed worktree but retained branch"));
assert!(removed.contains("/tmp/repo.feature-survivor"));
assert!(!removed.contains("moved during deletion"));
assert!(!removed.contains("not integrated"));
let branch_only = retained_checked_out_branch_message("feature", path, false);
assert!(branch_only.contains("Retained branch"));
assert!(!branch_only.contains("Removed worktree"));
}
/// A failed branch query must not cancel a removal that Git can perform.
#[test]
fn detached_fallback_schedules_removal_after_branch_preparation_error() {
let mut test = worktrunk::testing::TestRepo::with_initial_commit();
let checkout = test.add_worktree("feature");
let repo = Repository::at(test.root_path()).unwrap();
let trash = repo.wt_trash_dir();
std::fs::create_dir_all(trash.parent().unwrap()).unwrap();
std::fs::write(&trash, "block staging").unwrap();
let outcome = execute_instant_removal_or_fallback(
&repo,
&BackgroundRemoval {
worktree_path: &checkout,
branch_name: Some("feature"),
deletion_mode: BranchDeletionMode::SafeDelete,
target_branch: Some("missing-target"),
force_worktree: false,
changed_directory: false,
planner_expected_retention: false,
},
BackgroundFallbackMode::Detached,
|_, _| unreachable!("the blocked staging path must defer removal"),
)
.unwrap();
assert!(format!("{:#}", outcome.branch_fate.unwrap_err()).contains("missing-target"));
let BackgroundRemovalPlan::Deferred(args) = outcome.plan else {
panic!("the checkout removal must still be scheduled");
};
let shell = worktrunk::shell_exec::ShellConfig::get().unwrap();
let output = Cmd::new(shell.executable.to_str().unwrap())
.args(&shell.args)
.args(&args)
.current_dir(test.root_path())
.run()
.unwrap();
assert!(output.status.success(), "{output:?}");
assert!(!checkout.exists());
assert!(
repo.run_command(&["rev-parse", "--verify", "feature"])
.is_ok()
);
}
#[cfg(target_os = "linux")]
#[test]
fn background_removal_preserves_native_path_arguments() {
use std::os::unix::ffi::{OsStrExt, OsStringExt};
let mut test = worktrunk::testing::TestRepo::with_initial_commit();
let original = test.add_worktree("feature");
let repo = Repository::at(test.root_path()).unwrap();
let registration = repo.worktree_at(&original).git_dir().unwrap();
let checkout =
original.with_file_name(std::ffi::OsString::from_vec(b"feature-\xff".to_vec()));
std::fs::rename(&original, &checkout).unwrap();
let mut backlink = checkout.join(".git").as_os_str().as_bytes().to_vec();
backlink.push(b'\n');
std::fs::write(registration.join("gitdir"), &backlink).unwrap();
execute_instant_removal_or_fallback(
&repo,
&BackgroundRemoval {
worktree_path: &checkout,
branch_name: Some("feature"),
deletion_mode: BranchDeletionMode::Keep,
target_branch: None,
force_worktree: false,
changed_directory: false,
planner_expected_retention: true,
},
BackgroundFallbackMode::Detached,
|args, _| {
assert_eq!(args.last().unwrap(), "_drain-trash");
worktrunk::git::drain_trash(&repo.wt_trash_dir())
},
)
.unwrap();
assert!(!checkout.exists());
// A concurrently forked test can inherit the drain lock until exec.
// Match the bounded retry in git::remove's drain test.
worktrunk::testing::wait_for("the staged worktree to be drained", || {
worktrunk::git::drain_trash(&repo.wt_trash_dir()).unwrap();
worktrunk::git::staged_trash_entries(&repo.wt_trash_dir()).is_empty()
});
assert!(!registration.exists());
assert!(
repo.run_command(&["rev-parse", "--verify", "feature"])
.is_ok()
);
}
#[test]
fn test_format_switch_message() {
let path = PathBuf::from("/tmp/test");
// Switched to existing worktree (no creation)
let msg = format_switch_message("feature", &path, false, false, None, None);
assert_snapshot!(msg, @"Switched to worktree for [1mfeature[22m @ [1m/tmp/test[22m");
// Created branch and worktree with --create
let msg = format_switch_message("feature", &path, true, true, Some("main"), None);
assert_snapshot!(msg, @"Created branch [1mfeature[22m from [1mmain[22m and worktree @ [1m/tmp/test[22m");
// Created worktree from remote (DWIM) - also creates local tracking branch
let msg =
format_switch_message("feature", &path, true, false, None, Some("origin/feature"));
assert_snapshot!(msg, @"Created branch [1mfeature[22m (tracking [1morigin/feature[22m) and worktree @ [1m/tmp/test[22m");
// Created worktree only (local branch already existed)
let msg = format_switch_message("feature", &path, true, false, None, None);
assert!(!msg.contains("branch")); // Should NOT mention branch creation
assert_snapshot!(msg, @"Created worktree for [1mfeature[22m @ [1m/tmp/test[22m");
}
#[test]
fn test_flag_note() {
// --no-delete-branch flag (text only, no symbol, no suffix)
let note = flag_note(
BranchDeletionMode::Keep,
&BranchDeletionOutcome::NotDeleted,
None,
);
assert_eq!(note.text, " (--no-delete-branch)");
assert!(note.symbol.is_none());
assert!(note.suffix.is_empty());
// NotDeleted without flag (empty)
let note = flag_note(
BranchDeletionMode::SafeDelete,
&BranchDeletionOutcome::NotDeleted,
None,
);
assert!(note.text.is_empty());
assert!(note.symbol.is_none());
assert!(note.suffix.is_empty());
// Force deleted (text only, no symbol, no suffix)
let note = flag_note(
BranchDeletionMode::ForceDelete,
&BranchDeletionOutcome::ForceDeleted,
None,
);
assert_eq!(note.text, " (--force-delete)");
assert!(note.symbol.is_none());
assert!(note.suffix.is_empty());
// Integration reasons - text includes description and target, symbol is separate, suffix is closing paren
let cases = [
(IntegrationReason::SameCommit, "same commit as"),
(IntegrationReason::Ancestor, "ancestor of"),
(IntegrationReason::NoAddedChanges, "no added changes on"),
(IntegrationReason::TreesMatch, "tree matches"),
(IntegrationReason::MergeAddsNothing, "all changes in"),
];
for (reason, expected_desc) in cases {
let note = flag_note(
BranchDeletionMode::SafeDelete,
&BranchDeletionOutcome::Integrated(reason),
Some("main"),
);
assert!(
note.text.contains(expected_desc),
"reason {:?} text should contain '{}'",
reason,
expected_desc
);
assert!(
note.text.contains("main"),
"reason {:?} text should contain target 'main'",
reason
);
assert!(
note.symbol.is_some(),
"reason {:?} should have a symbol",
reason
);
let symbol = note.symbol.as_ref().unwrap();
assert!(
symbol.contains(reason.symbol()),
"reason {:?} symbol part should contain the symbol",
reason
);
assert_eq!(
note.suffix, ")",
"reason {:?} suffix should be closing paren",
reason
);
}
}
#[test]
fn test_resolve_subdir_in_target_no_source_root() {
let target = PathBuf::from("/target/worktree");
let cwd = PathBuf::from("/some/dir");
assert_eq!(resolve_subdir_in_target(&target, None, &cwd), target);
}
#[test]
fn test_resolve_subdir_in_target_subdir_exists() {
let dir = worktrunk::testing::tempdir().unwrap();
let source = dir.path().join("source");
let target = dir.path().join("target");
std::fs::create_dir_all(source.join("apps/gateway")).unwrap();
std::fs::create_dir_all(target.join("apps/gateway")).unwrap();
let cwd = source.join("apps/gateway");
let result = resolve_subdir_in_target(&target, Some(&source), &cwd);
assert_eq!(result, target.join("apps/gateway"));
}
#[test]
fn test_resolve_subdir_in_target_subdir_deeper_than_windows_max_path() {
// A cwd nested past Windows' 260-character path limit comes back from
// `dunce` spelled `\\?\C:\…` while its short worktree root stays `C:\…`,
// so `strip_prefix` fails and the shell lands at the target root with no
// error rather than at the mirrored subdirectory (#3898). Off Windows
// the depth is unremarkable and this just exercises a deep tree.
let dir = worktrunk::testing::tempdir().unwrap();
let source = dir.path().join("source");
let target = dir.path().join("target");
let mut relative = PathBuf::from("node_modules");
while source.join(&relative).as_os_str().len() < 320 {
relative.push("nested-dependency-directory");
}
std::fs::create_dir_all(source.join(&relative)).unwrap();
std::fs::create_dir_all(target.join(&relative)).unwrap();
let result = resolve_subdir_in_target(&target, Some(&source), &source.join(&relative));
assert_eq!(result, target.join(&relative));
}
#[test]
fn test_resolve_subdir_in_target_subdir_missing() {
let dir = worktrunk::testing::tempdir().unwrap();
let source = dir.path().join("source");
let target = dir.path().join("target");
std::fs::create_dir_all(source.join("apps/gateway")).unwrap();
std::fs::create_dir_all(&target).unwrap();
let cwd = source.join("apps/gateway");
let result = resolve_subdir_in_target(&target, Some(&source), &cwd);
assert_eq!(result, target); // Falls back to root
}
#[test]
fn test_resolve_subdir_in_target_at_root() {
let dir = worktrunk::testing::tempdir().unwrap();
let source = dir.path().join("source");
let target = dir.path().join("target");
std::fs::create_dir_all(&source).unwrap();
std::fs::create_dir_all(&target).unwrap();
let result = resolve_subdir_in_target(&target, Some(&source), &source);
assert_eq!(result, target);
}
#[test]
fn test_git_subcommand_warning() {
let warning = git_subcommand_warning();
assert_snapshot!(warning, @"For automatic cd, invoke directly (with the [4m-[24m): [4mgit-wt[24m");
}
}