Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Worktree removal with fast-path trash staging and safe branch deletion.
//!
//! Two entry points:
//!
//! - [`stage_worktree_removal`] — the ordered prelude every removal path runs
//! in the foreground before the worktree directory stops existing: the
//! dirty-worktree gate, the fsmonitor stop, then the
//! rename into trash. It owns the gates, so it is the one place removal's
//! data safety is decided.
//! - [`remove_worktree_with_cleanup`] — that prelude, plus the direct-removal
//! fallback and branch deletion, run to completion synchronously.
//!
//! The split exists because the default path defers its deletion: `wt remove`
//! and `wt merge --remove` stage the worktree here, then hand the deletion to
//! a detached [`drain_trash`] so the command returns as soon as the workspace
//! is clear. They build that tail themselves rather than calling
//! [`remove_worktree_with_cleanup`]. The callers that run to completion —
//! `--foreground` removals, the TUI picker, and external tooling (e.g.
//! `worktrunk-sync`) — call it and get the fallback and integration-checked
//! branch deletion for free.
//!
//! # What happens during removal
//!
//! Steps 1-3 are [`stage_worktree_removal`]; 4-5 are the rest of
//! [`remove_worktree_with_cleanup`].
//!
//! 1. **Lock and clean checks**. A `git worktree lock` is refused
//! unconditionally (matching `git worktree remove`; `--force` does not
//! override it). The dirty-worktree gate is skipped with
//! [`RemoveOptions::force_worktree`], which reports the current uncommitted
//! paths, or why they could not be read, before deletion instead, and
//! backs those changes up to `refs/wt-backup/<branch>` (ignored files
//! excepted); a failed backup refuses the removal. Why the
//! dirty gate precedes the stop below: [`stage_worktree_removal`], "Why this order".
//! 2. **fsmonitor daemon stopped** (best effort). [`stop_fsmonitor_daemon`]
//! runs against the target worktree before its path disappears: it sends
//! the graceful `git fsmonitor--daemon stop` IPC request, then verifies the
//! daemon is actually gone and force-kills it by PID if it has wedged.
//! Without this, a daemon that has stopped answering its socket leaks
//! forever once its worktree is removed. With fsmonitor configured, the
//! clean check then reruns without it, catching writes during shutdown.
//! 3. **Fast-path trash staging.** The worktree directory is renamed into
//! `<git-common-dir>/wt/trash/<name>-<timestamp>/`. Same-filesystem renames
//! are instant metadata operations, so the user's workspace clears
//! immediately. The caller is responsible for eventually removing the
//! staged path — either synchronously or via [`drain_trash`] in a
//! background process.
//! 4. **Fallback removal.** If the rename fails (cross-filesystem, permission
//! denied, Windows file locks), the code falls back to `git worktree remove`
//! (optionally with `--force`), which deletes files directly.
//! 5. **Branch deletion** (optional). When a branch name is supplied, the
//! branch is deleted according to the requested [`BranchDeletionMode`]:
//! - [`Keep`](BranchDeletionMode::Keep): never delete.
//! - [`SafeDelete`](BranchDeletionMode::SafeDelete): delete only if
//! [`Repository::integration_reason`] reports the branch as integrated
//! into `target_branch` (or `HEAD` when unspecified).
//! - [`ForceDelete`](BranchDeletionMode::ForceDelete): run `branch -D`
//! without the integration check.
//!
//! # The dirty-worktree gate
//!
//! Under `core.fsmonitor` the daemon answers step 1's `git status`, as it
//! answers `git worktree remove`'s. That first gate refuses a dirty worktree
//! cheaply and leaves its daemon running.
//!
//! Stopping the daemon is `wt`'s own step, not git's, and it opens a window
//! git's gate never has: writes during the shutdown. So with fsmonitor
//! configured the gate runs again after the stop, rescanning without the
//! daemon, and that rescan is what a clean removal passes. It costs one full
//! re-stat per removal where fsmonitor is configured, and also catches a
//! stale clean answer from the daemon, which makes `wt` stricter there than
//! `git worktree remove`. (`--no-optional-locks` cannot replace the rescan: it
//! governs index-lock acquisition, and git still queries the daemon under it.)
//!
//! # Example
//!
//! ```no_run
//! use std::path::Path;
//! use worktrunk::git::{
//! BranchDeletionMode, RemoveOptions, Repository, remove_worktree_with_cleanup,
//! };
//!
//! let repo = Repository::current()?;
//! let snapshot = repo.capture_refs()?;
//! let output = remove_worktree_with_cleanup(
//! &repo,
//! &snapshot,
//! Path::new("/repos/myproject.feature"),
//! RemoveOptions {
//! branch: Some("feature".into()),
//! deletion_mode: BranchDeletionMode::SafeDelete,
//! target_branch: Some("main".into()),
//! force_worktree: false,
//! },
//! )?;
//!
//! // Caller cleans up the staged trash entry (sync or background).
//! if let Some(staged) = output.staged_path {
//! let _ = std::fs::remove_dir_all(staged);
//! }
//! # Ok::<(), anyhow::Error>(())
//! ```
use std::collections::HashSet;
use std::fs::{self, TryLockError};
use std::path::{Path, PathBuf};
use std::time::Duration;
use anyhow::Context as _;
use crate::git::repository::WorkingTree;
use crate::git::{ErrorExt, GitError, IntegrationReason, Repository, WorktreeInfo, path_dir_name};
use crate::path::format_path_for_display;
use crate::progress::Progress;
use crate::remove_dir::remove_dir_with_progress;
use crate::shell_exec::Cmd;
use crate::styling::{eprintln, format_with_gutter, warning_message};
use crate::utils::epoch_now;
/// Bound on the graceful `git fsmonitor--daemon stop` IPC request.
///
/// `stop` is itself an IPC call to the daemon, so a wedged daemon (the failure
/// this whole helper exists for) makes it hang. The force-kill path below is
/// what actually reaps such a daemon; this timeout just stops the graceful
/// attempt from blocking `wt remove` while the daemon ignores it.
const FSMONITOR_STOP_TIMEOUT: Duration = Duration::from_secs(2);
/// Bound on the `lsof` socket→PID lookup.
#[cfg(unix)]
const FSMONITOR_LSOF_TIMEOUT: Duration = Duration::from_secs(2);
/// Stop the fsmonitor daemon serving `worktree`, force-killing it if it has
/// stopped answering its IPC socket.
///
/// `git fsmonitor--daemon` is a per-worktree, self-respawning filesystem-watch
/// cache git starts when `core.fsmonitor=true`. The graceful shutdown,
/// `git fsmonitor--daemon stop`, is an IPC request *to the daemon itself*: a
/// wedged daemon (one that has stopped answering its socket — the common
/// failure, which also hangs `git status` in that worktree) silently ignores
/// `stop` and then leaks forever once its worktree is gone, since nothing else
/// references it. Worktree removal is the one moment we can still identify the
/// daemon by its socket, so this verifies the daemon is actually gone after
/// `stop` and, on Unix, kills it by PID (SIGTERM, brief wait, SIGKILL) if not.
///
/// This is the single canonical fsmonitor-stop path. It runs **synchronously
/// while the worktree path still exists** (the socket lives under the
/// per-worktree git dir and is needed to resolve the owning PID), so its one
/// caller is [`stage_worktree_removal`], which every removal path runs in the
/// foreground before the directory is staged or pruned. The detached trash drain
/// never touches the daemon; keeping daemon management in
/// the Rust foreground avoids reimplementing socket/PID resolution and signal
/// escalation as a shell string.
///
/// Best-effort and fail-open: every step is bounded by a timeout and every
/// error is logged at debug level and swallowed. A failure here must never
/// fail or materially slow `wt remove`. The PID is only ever resolved from the
/// IPC socket *inside the specific worktree being removed*, so a signal can
/// only ever reach that worktree's own daemon, never another worktree's.
pub fn stop_fsmonitor_daemon(worktree: &WorkingTree) {
// Graceful path first: a healthy daemon exits cleanly on this IPC request.
let _ = Cmd::new("git")
.args(["fsmonitor--daemon", "stop"])
.current_dir(worktree.path())
.context(crate::git::repository::path_to_logging_context(
worktree.path(),
))
.timeout(FSMONITOR_STOP_TIMEOUT)
.run();
// Resolve the per-worktree git dir via git (handles the `.git` *file* a
// linked worktree uses — never hand-construct `<path>/.git`). The daemon
// binds its IPC socket at `<git-dir>/fsmonitor--daemon.ipc`.
let socket = match worktree.git_dir() {
Ok(git_dir) => git_dir.join(super::fsmonitor::IPC_SOCKET_NAME),
Err(e) => {
tracing::debug!(error = %e, "fsmonitor: could not resolve git dir, skipping force-kill: {e}");
return;
}
};
force_kill_fsmonitor_via_socket(&socket);
}
/// Unix: if `socket` still exists, find the daemon owning it via `lsof` and
/// terminate it (SIGTERM, bounded wait, SIGKILL).
///
/// `lsof -t -- <socket>` prints just the owning PID(s), one per line, and
/// exits 0 when found / 1 when nothing holds the socket. (`--` ends option
/// parsing so a socket path is never mistaken for a flag.) Matching by socket
/// path (not process name) guarantees a signal only ever reaches the daemon
/// for *this* worktree: a different worktree's daemon binds a different socket,
/// and once the daemon exits nothing holds the socket so `lsof` returns no
/// PID — a dead daemon's reused PID is therefore never reported here.
#[cfg(unix)]
fn force_kill_fsmonitor_via_socket(socket: &Path) {
// No socket means `stop` already reaped a healthy daemon (or one never ran).
if !socket.exists() {
return;
}
let output = match Cmd::new("lsof")
.arg("-t")
.arg("--")
.arg(socket)
.timeout(FSMONITOR_LSOF_TIMEOUT)
.run()
{
Ok(output) => output,
Err(e) => {
tracing::debug!(error = %e, "fsmonitor: lsof failed, cannot force-kill: {e}");
return;
}
};
let pids: Vec<u32> = String::from_utf8_lossy(&output.stdout)
.lines()
.filter_map(|line| line.trim().parse::<u32>().ok())
.collect();
super::fsmonitor::escalate_terminate(
&super::fsmonitor::NixSignaller,
&pids,
super::fsmonitor::REAP_KILL_DEADLINE,
);
}
/// Non-Unix: the daemon uses a named pipe rather than a Unix-domain socket, so
/// the `lsof`-by-socket reaping doesn't apply. The graceful IPC `stop` in
/// [`stop_fsmonitor_daemon`] is the only stop mechanism here.
#[cfg(not(unix))]
fn force_kill_fsmonitor_via_socket(_socket: &Path) {}
/// How the branch should be handled after worktree removal.
///
/// Replaces a two-boolean flag pair (`keep`/`force`) to make the three valid
/// states explicit and prevent invalid combinations (e.g. keep+force).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum BranchDeletionMode {
/// Keep the branch regardless of merge status (`--no-delete-branch`).
Keep,
/// Delete only if integrated into the target branch (default).
#[default]
SafeDelete,
/// Delete the branch even if not merged (`-D`).
ForceDelete,
}
impl BranchDeletionMode {
/// Construct from CLI-style flags.
///
/// `keep_branch` takes precedence over `force_delete`.
pub fn from_flags(keep_branch: bool, force_delete: bool) -> Self {
if keep_branch {
Self::Keep
} else if force_delete {
Self::ForceDelete
} else {
Self::SafeDelete
}
}
/// Whether the branch should be kept (never deleted).
pub fn should_keep(&self) -> bool {
matches!(self, Self::Keep)
}
/// Whether to force-delete even if unmerged.
pub fn is_force(&self) -> bool {
matches!(self, Self::ForceDelete)
}
}
/// Outcome of a branch-deletion attempt.
pub enum BranchDeletionOutcome {
/// Branch was not deleted — it was not integrated, and deletion was not forced.
NotDeleted,
/// Branch was integrated, but a fresh topology read found it checked out in
/// a worktree before the deletion attempt. The ref is retained so that
/// worktree's HEAD remains resolvable.
RetainedCheckedOut { path: PathBuf },
/// Branch was integrated but the atomic compare-and-swap deletion was
/// rejected because the ref moved between the integration check and the
/// delete attempt — e.g. a hook or concurrent process advanced it. The
/// branch is retained (fail-closed), and the caller surfaces this as a
/// warning so the user can decide whether to re-check and delete.
RetainedRaced,
/// Branch was force-deleted without an integration check.
ForceDeleted,
/// Branch was deleted because it was integrated (the specific reason is attached).
Integrated(IntegrationReason),
}
/// Result of [`delete_branch_if_safe`].
pub struct BranchDeletionResult {
pub outcome: BranchDeletionOutcome,
/// The ref actually checked against.
///
/// May differ from the caller-supplied target when the local branch is
/// behind its upstream — in that case `integration_reason` substitutes the
/// upstream ref so users don't get false negatives.
pub integration_target: String,
}
/// Options for [`remove_worktree_with_cleanup`].
///
/// Typical usage:
///
/// ```
/// use worktrunk::git::{BranchDeletionMode, RemoveOptions};
///
/// let options = RemoveOptions {
/// branch: Some("feature".into()),
/// deletion_mode: BranchDeletionMode::SafeDelete,
/// target_branch: Some("main".into()),
/// force_worktree: false,
/// };
///
/// // Or, to delete a worktree without touching the branch:
/// let options = RemoveOptions {
/// branch: Some("feature".into()),
/// deletion_mode: BranchDeletionMode::Keep,
/// ..Default::default()
/// };
/// ```
#[derive(Debug, Clone, Default)]
pub struct RemoveOptions {
/// Branch name to delete alongside the worktree.
///
/// `None` skips branch handling (useful for detached-HEAD worktrees).
pub branch: Option<String>,
/// How to handle the branch (default: [`BranchDeletionMode::SafeDelete`]).
pub deletion_mode: BranchDeletionMode,
/// Integration target for the safety check.
///
/// Only consulted when `deletion_mode` is [`BranchDeletionMode::SafeDelete`].
/// `None` falls back to `HEAD`.
pub target_branch: Option<String>,
/// Skip the clean check and pass `--force` to the `git worktree remove`
/// fallback.
///
/// Trash staging itself is unconditional and always preserves data (the
/// renamed directory can be recovered from `<git-common-dir>/wt/trash/`
/// until the caller deletes it).
pub force_worktree: bool,
}
/// Result of [`remove_worktree_with_cleanup`].
///
/// `branch_result` is `None` when deletion was skipped (no branch supplied, or
/// `deletion_mode.should_keep()`). A deletion failure carries
/// [`GitError::BranchDeletionFailed`] with the removed worktree's path.
/// Callers finish teardown and cleanup before propagating it.
///
/// `staged_path` is `Some` only on the fast path. Callers are responsible for
/// cleaning up the staged directory; `wt remove` does this with a detached
/// [`drain_trash`] so the foreground command returns immediately.
pub struct RemovalOutput {
pub branch_result: Option<anyhow::Result<BranchDeletionResult>>,
/// Path to the staged trash directory on the fast path.
///
/// `None` if the fast-path rename failed and the fallback `git worktree
/// remove` was used.
pub staged_path: Option<PathBuf>,
}
/// Remove a worktree with fsmonitor cleanup, fast-path trash staging, and
/// optional safe branch deletion.
///
/// See the [module-level docs](self) for the full flow.
///
/// # Errors
///
/// - Returns an error if the fast-path rename fails **and** the fallback
/// `git worktree remove` also fails.
/// - Branch-deletion errors are captured in
/// [`RemovalOutput::branch_result`] rather than returned — worktree removal
/// is already complete. Callers finish teardown and cleanup before
/// propagating the contextual deletion failure.
pub fn remove_worktree_with_cleanup(
repo: &Repository,
snapshot: &crate::git::RefSnapshot,
worktree_path: &Path,
options: RemoveOptions,
) -> anyhow::Result<RemovalOutput> {
let staged_path = stage_worktree_removal(
repo,
worktree_path,
options.branch.as_deref(),
options.force_worktree,
)?;
if staged_path.is_none() {
repo.remove_worktree(worktree_path, options.force_worktree)?;
}
// Delete branch if safe
let branch_result = if let Some(branch) = options.branch.as_deref()
&& !options.deletion_mode.should_keep()
{
let target = options.target_branch.as_deref().unwrap_or("HEAD");
Some(
delete_branch_if_safe(
repo,
snapshot,
branch,
target,
options.deletion_mode.is_force(),
)
.map_err(|error| {
GitError::BranchDeletionFailed {
branch: branch.to_owned(),
removed_worktree: Some(worktree_path.to_path_buf()),
error,
}
.into()
}),
)
} else {
None
};
Ok(RemovalOutput {
branch_result,
staged_path,
})
}
/// Gate, stop the fsmonitor daemon, and stage a worktree for removal — steps
/// 1-3 of the [module-level docs](self), in that order.
///
/// Every removal path runs this, in the foreground, before the worktree
/// directory stops existing: the synchronous
/// [`remove_worktree_with_cleanup`], and the default background path, which
/// stages here and hands the deletion to a detached [`drain_trash`]. Keeping the three
/// steps together is what makes the dirty-worktree gate a single decision
/// rather than a sequence each caller re-assembles — the order below is easy
/// to get subtly wrong, and getting it wrong destroys uncommitted work.
///
/// Returns `Some(staged_path)` when the worktree was renamed into
/// `<git-common-dir>/wt/trash/`, `None` when the rename failed
/// (cross-filesystem, permissions, Windows file locking) and the caller must
/// fall back to a direct `git worktree remove`. Either way the caller owns the
/// staged directory and must eventually delete it.
///
/// # Why this order
///
/// The gate runs **before** the daemon stop so a dirty worktree is refused off
/// the daemon's cheap answer, with its daemon left running. With fsmonitor
/// configured it runs once more after the stop, rescanning, to catch writes
/// during the shutdown — see "The dirty-worktree gate" in the
/// [module-level docs](self).
///
/// The daemon stop runs **before** the rename because on Windows the daemon
/// holds a handle on the worktree that would fail it, and git's graceful stop
/// resolves the daemon by worktree path — unreachable once the path moves.
///
/// The ownership check runs **before** the dirty-worktree gate, and outside
/// the `force_worktree` branch that skips it. Both matter. The gate reads `git
/// status` in the directory, so against a foreign occupant it reports *that*
/// repository's dirt as this worktree's and offers `--force` as the remedy — a
/// hint leading straight to the deletion the check refuses. And `--force` is
/// the user waiving their own uncommitted changes, never a claim about who
/// owns the directory, so it cannot be allowed to skip it; git's own
/// validation is likewise unconditional. The lock check sits with ownership:
/// `--force` does not override `git worktree lock`, and the check reads the
/// `locked` file rather than `list_worktrees()`, whose `RepoCache` entry
/// planning already warmed: it would answer from before the approval prompt
/// and the `pre-remove` hook, which is the window this call closes.
///
/// `wt remove` and `wt merge --remove` have already asked this during
/// planning, where the answer can precede the "Removing …" announcement. The
/// call here still re-reads the directory's `.git` entry, so it also closes the
/// window those two leave open: the approval prompt and the `pre-remove` hook
/// run between their check and this rename.
///
/// # Errors
///
/// The ownership, lock, and dirty-worktree gates error, as does a failed
/// `--force` backup of uncommitted changes. A
/// failed rename is reported as `None`, not an error, and the daemon stop is
/// best-effort throughout.
pub fn stage_worktree_removal(
repo: &Repository,
worktree_path: &Path,
branch: Option<&str>,
force_worktree: bool,
) -> anyhow::Result<Option<PathBuf>> {
let worktree = repo.worktree_at(worktree_path);
let git_dir = worktree.ensure_holds_this_worktree()?;
// Lock is the user's explicit "don't remove this". `--force` does not
// override it, matching `git worktree remove` and `prepare_worktree_removal`.
// Read the `locked` file rather than `list_worktrees()`: its `RepoCache`
// entry is already warm from planning, so it would report the lock state
// from before the approval prompt and the `pre-remove` hook.
if let Some(reason) = worktree.lock_reason()? {
let name = branch
.unwrap_or_else(|| path_dir_name(worktree_path))
.to_string();
return Err(GitError::WorktreeLocked {
branch: name,
path: worktree_path.to_path_buf(),
reason,
}
.into());
}
if force_worktree {
// Disclosure does not veto the force removal, but an interrupted
// status command still cancels before any directory is removed.
match worktree.dirty_files() {
Ok(dirty_files) if !dirty_files.is_empty() => {
// `--force` waives the dirty gate, not recoverability. A
// failed backup refuses the removal rather than lose the
// changes it was meant to keep, so the discard is announced
// only once the backup exists.
let name = branch.unwrap_or_else(|| path_dir_name(worktree_path));
let backup = worktree
.create_removal_backup(&format!("{name} (remove --force)"))
.context("Failed to back up uncommitted changes; worktree not removed")?;
eprintln!(
"{}",
warning_message("Discarding uncommitted changes (--force):")
);
eprintln!("{}", format_with_gutter(&dirty_files.join("\n"), None));
backup.print_recovery_hints(repo)?;
}
Ok(_) => {}
Err(error) => {
if error.interrupt_signal().is_some() {
return Err(error);
}
eprintln!(
"{}",
warning_message(
"Cannot list uncommitted changes; discarding worktree contents (--force):"
)
);
eprintln!("{}", format_with_gutter(&error.display_message(), None));
}
}
} else {
worktree.ensure_clean("remove worktree", branch, true)?;
}
stop_fsmonitor_daemon(&worktree);
// The daemon answered the gate above, and a write can land while it shuts
// down. Recheck without it; with fsmonitor configured, a plain status
// would start a new daemon in the worktree about to go.
if !force_worktree && repo.is_builtin_fsmonitor_enabled() {
worktree.ensure_clean_without_fsmonitor("remove worktree", branch, true)?;
}
Ok(rename_into_trash(repo, worktree_path, &git_dir))
}
/// Find a registered worktree contained in `worktree_path`, using a fresh
/// registry read. Ignored nested worktrees are invisible to `ensure_clean`,
/// but renaming or removing their parent would destroy their independent work.
/// Canonical paths catch registrations made through symlinks; a missing entry
/// has no directory to protect, while other resolution errors fail closed.
///
/// Called only by merge cleanup: once while deciding whether to remove, then
/// again after approved pre-remove hooks and before the final removal gates.
/// Keep this live registry read out of `stage_worktree_removal`: batch prune
/// staging must not wait for another removal's registry teardown (#3954).
pub fn nested_worktree(repo: &Repository, worktree_path: &Path) -> anyhow::Result<Option<PathBuf>> {
let root =
dunce::canonicalize(worktree_path).context("Failed to resolve worktree for removal")?;
let fresh_repo = Repository::at(repo.discovery_path())?;
for worktree in fresh_repo.list_worktrees()? {
let path = match dunce::canonicalize(&worktree.path) {
Ok(path) => path,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
Err(error) => {
return Err(error).with_context(|| {
format!(
"Failed to resolve worktree @ {}",
format_path_for_display(&worktree.path)
)
});
}
};
if path != root && path.starts_with(&root) {
return Ok(Some(path));
}
}
Ok(None)
}
/// Rename a worktree into `<git-common-dir>/wt/trash/` and prune git metadata.
///
/// Returns `Some(staged_path)` on success, `None` if the rename failed. The
/// unguarded mutation: [`stage_worktree_removal`] is the only caller, and it
/// is what places the dirty-worktree gate ahead of this.
///
/// The metadata cleanup names this worktree
/// ([`prune_worktree_entry`](Repository::prune_worktree_entry)) rather than
/// sweeping the repository, so a sibling worktree whose directory happens to
/// be absent right now keeps its registration. A locked worktree never reaches
/// here — [`stage_worktree_removal`] rejects one before the rename.
fn rename_into_trash(repo: &Repository, worktree_path: &Path, git_dir: &Path) -> Option<PathBuf> {
let trash_dir = repo.wt_trash_dir();
let _ = std::fs::create_dir_all(&trash_dir);
let staged_path = generate_removing_path(&trash_dir, git_dir);
if std::fs::rename(worktree_path, &staged_path)
.inspect_err(|e| {
tracing::debug!(error = %e, "Failed to stage worktree into trash, falling back: {e}");
})
.is_ok()
{
// The rename moved the directory out from under `worktree_path`,
// leaving its registration stale for the prune to delete.
if let Err(e) = repo.prune_worktree_entry(worktree_path) {
tracing::debug!(error = %e, "Failed to prune worktree entry after rename: {e}");
}
Some(staged_path)
} else {
None
}
}
/// Capture fresh refs and run branch deletion.
///
/// Used after worktree removal and for branch-only deletion. Every path,
/// including the detached fallback, uses [`delete_branch_if_safe`] to recheck
/// integration and checkout ownership; safe deletion uses CAS against the captured tip.
pub fn execute_branch_deletion(
repo: &Repository,
branch_name: &str,
target: &str,
force_delete: bool,
) -> anyhow::Result<BranchDeletionResult> {
let snapshot = repo.capture_refs()?;
delete_branch_if_safe(repo, &snapshot, branch_name, target, force_delete)
}
/// Delete a branch if its content is integrated into the target, or if
/// `force_delete` is set.
///
/// The integration check is the same logic `wt list` uses for its status
/// column — see [`IntegrationReason`] for the full set of recognised cases
/// (same-commit, ancestor, squash-merged, etc.).
///
/// Returns a [`BranchDeletionResult`] rather than raising an error for the
/// "not integrated" case — that's a normal outcome and the caller decides how
/// to surface it. Failures to read current topology or run the Git mutation
/// propagate as `Err`.
pub fn delete_branch_if_safe(
repo: &Repository,
snapshot: &crate::git::RefSnapshot,
branch_name: &str,
target: &str,
force_delete: bool,
) -> anyhow::Result<BranchDeletionResult> {
// Force-delete: skip integration check entirely (matches compute_integration_reason
// behavior for the Worktree path). The user explicitly chose -D.
if force_delete {
repo.run_command(&["branch", "-D", "--", branch_name])?;
repo.clear_branch_marker(branch_name);
return Ok(BranchDeletionResult {
outcome: BranchDeletionOutcome::ForceDeleted,
integration_target: target.to_string(),
});
}
let (effective_target, reason) = repo.integration_reason(snapshot, branch_name, target)?;
let outcome = match reason {
Some(r) => {
// Atomic compare-and-swap against the snapshotted SHA. If the ref
// moved between `integration_reason` and the delete (e.g. a hook
// advanced the branch), the `git update-ref` mutation fails
// closed: the branch is retained and we surface a `RetainedRaced`
// outcome rather than dropping the unmerged commits silently.
//
// Read the SHA from the snapshot inventory (`local_branch`) rather
// than `resolve()`, so it reflects the same `refs/heads/` walk
// `integration_reason` consulted.
let Some(branch) = snapshot.local_branch(branch_name) else {
anyhow::bail!(
"Cannot safely delete branch {branch_name}: absent from ref snapshot"
);
};
cas_delete_branch_outcome(repo, branch_name, &branch.commit_sha, r)?
}
None => BranchDeletionOutcome::NotDeleted,
};
if matches!(outcome, BranchDeletionOutcome::Integrated(_)) {
repo.clear_branch_marker(branch_name);
}
Ok(BranchDeletionResult {
outcome,
integration_target: effective_target,
})
}
/// Find a live checkout of `branch` using a new repository cache.
///
/// Removal planning intentionally caches `git worktree list`, but branch
/// deletion happens after hooks and other concurrent actors may have changed
/// topology. Constructing a new [`Repository`] is the cache boundary: its first
/// `list_worktrees` call executes a fresh `git worktree list --porcelain`.
///
/// Git still lists stale registrations whose directories are gone, marking
/// them `prunable`; those have no live checkout to orphan and must not strand
/// the branch. Missing locked worktrees remain non-prunable, so their lock
/// continues to retain the branch conservatively.
fn fresh_branch_checkout(repo: &Repository, branch_name: &str) -> anyhow::Result<Option<PathBuf>> {
let fresh_repo = Repository::at(repo.discovery_path())?;
Ok(fresh_repo
.list_worktrees()?
.iter()
.find(|worktree| branch_checkout_requires_retention(worktree, branch_name))
.map(|worktree| worktree.path.clone()))
}
/// Whether deleting `branch` would risk orphaning this worktree record.
///
/// Git normally reports a missing locked worktree as `locked` but not
/// `prunable`. Letting the lock win explicitly keeps the guard fail-closed if a
/// Git version or synthetic porcelain record ever carries both fields.
fn branch_checkout_requires_retention(worktree: &WorktreeInfo, branch_name: &str) -> bool {
worktree.branch.as_deref() == Some(branch_name)
&& (!worktree.is_prunable() || worktree.locked.is_some())
}
/// Atomically delete `refs/heads/<branch>` iff it currently points at
/// `expected_sha`, and translate the result into a [`BranchDeletionOutcome`].
///
/// `git update-ref -d <ref> <original-sha>` removes the ref only if its current
/// value still matches. The repository coordinator serializes these mutations
/// to avoid contention on Git's packed-refs lock.
///
/// A fresh topology read provides best-effort checkout protection before
/// acquiring the deletion mutex. Topology reads can run concurrently. Git has
/// no transaction spanning checkout state and a ref update: a checkout can
/// appear after this check, including during the mutex wait. The atomic SHA
/// comparison still protects concurrent commits.
///
/// On failure, a fresh exact ref read distinguishes actual SHA movement from
/// a lock or I/O error without parsing Git's localized diagnostics. A missing,
/// unchanged or unreadable ref propagates the original deletion error.
fn cas_delete_branch_outcome(
repo: &Repository,
branch_name: &str,
expected_sha: &str,
reason: IntegrationReason,
) -> anyhow::Result<BranchDeletionOutcome> {
let ref_name = format!("refs/heads/{branch_name}");
// update-ref bypasses Git's checked-out-branch protection. Sample topology
// from a fresh Repository cache, independent of the planning-time cache.
if let Some(path) = fresh_branch_checkout(repo, branch_name)? {
return Ok(BranchDeletionOutcome::RetainedCheckedOut { path });
}
if repo
.branch_deletions()
.delete(repo, &ref_name, expected_sha)?
{
Ok(BranchDeletionOutcome::Integrated(reason))
} else {
Ok(BranchDeletionOutcome::RetainedRaced)
}
}
/// Generate a staging path for worktree removal.
///
/// Places the staging directory inside `<git-common-dir>/wt/trash/` so it is
/// hidden from the user's workspace. For the main worktree, `.git/` is on the
/// same filesystem, so `rename()` is an instant metadata operation. Linked
/// worktrees on different mount points will get EXDEV and fall back to the
/// `git worktree remove` path.
///
/// Format: `<trash-dir>/<name>-<timestamp>`, where `<name>` is the final
/// component of the worktree's `git_dir`: its registration id under
/// `<common>/worktrees/`, which git keeps unique among a repository's
/// worktrees. The directory's basename is not unique — Codex places every
/// worktree at `<id>/<repo>` — and two removals sharing a staging path in the
/// same second would make the second rename fail onto the synchronous
/// fallback.
pub(crate) fn generate_removing_path(trash_dir: &Path, git_dir: &Path) -> PathBuf {
let timestamp = epoch_now();
let name = git_dir
.file_name()
.map(|n| n.to_string_lossy())
.unwrap_or_default();
trash_dir.join(format!("{}-{}", name, timestamp))
}
/// Entries in `trash_dir` named `<name>-<timestamp>`, as removal stages them.
///
/// Anything else in the directory was not staged by worktrunk and is left
/// alone. A missing directory has no entries.
pub fn staged_trash_entries(trash_dir: &Path) -> Vec<PathBuf> {
let Ok(read_dir) = fs::read_dir(trash_dir) else {
return Vec::new();
};
read_dir
.filter_map(|entry| entry.ok())
.filter(|entry| {
entry.file_name().to_str().is_some_and(|name| {
name.rsplit_once('-')
.is_some_and(|(_, timestamp)| timestamp.parse::<u64>().is_ok())
})
})
.map(|entry| entry.path())
.collect()
}
/// Whether a drain holds `trash_dir`'s lock.
///
/// A removal that finds one running skips starting another: the running drain
/// lists the trash again before it exits. The check holds the lock for an
/// instant, so a drain starting at that moment may exit early; the check then
/// reports no drain running and the caller starts one.
pub fn trash_drain_running(trash_dir: &Path) -> bool {
open_drain_lock(trash_dir)
.is_ok_and(|lock| matches!(lock.try_lock(), Err(TryLockError::WouldBlock)))
}
fn open_drain_lock(trash_dir: &Path) -> anyhow::Result<fs::File> {
let lock_path = trash_dir.with_extension("lock");
fs::OpenOptions::new()
.create(true)
.truncate(false)
.write(true)
.open(&lock_path)
.with_context(|| format!("Failed to open {}", format_path_for_display(&lock_path)))
}
/// Delete every staged entry in `trash_dir`, unless another drain is running.
///
/// Concurrent deletions on one filesystem add CPU without adding throughput:
/// a 193-worktree prune ran 193 `rm -rf` processes using about three cores to
/// delete 1,500 files/s, where one process alone deleted 3,000–5,000 files/s
/// at under one core. So one drain per trash directory does the deleting.
///
/// The running drain holds an exclusive lock on `<trash_dir>.lock`. A drain
/// that finds the lock held exits and leaves its entry to the holder, which
/// lists the directory again after each pass. After releasing the lock, the
/// holder lists once more and, if it finds a new entry, takes the lock again:
/// an entry staged while the holder was releasing it would otherwise wait for
/// the next removal.
///
/// An entry that a drain can't fully delete, such as one holding another
/// user's files, stays in the trash for a later drain rather than being
/// retried in a loop.
pub fn drain_trash(trash_dir: &Path) -> anyhow::Result<()> {
let mut undeletable = HashSet::new();
loop {
let lock = open_drain_lock(trash_dir)?;
match lock.try_lock() {
Err(TryLockError::WouldBlock) => return Ok(()),
result => result
.map_err(std::io::Error::from)
.context("Failed to lock the trash for deletion")?,
}
loop {
let pending: Vec<_> = staged_trash_entries(trash_dir)
.into_iter()
.filter(|entry| !undeletable.contains(entry))
.collect();
if pending.is_empty() {
break;
}
for entry in pending {
if !remove_dir_with_progress(&entry, &Progress::disabled()) {
undeletable.insert(entry);
}
}
}
drop(lock);
if staged_trash_entries(trash_dir)
.iter()
.all(|entry| undeletable.contains(entry))
{
return Ok(());
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::git::ErrorExt;
use crate::testing::TestRepo;
/// A drain deletes worktrunk's staged entries and leaves anything else; a
/// drain that finds another holding the lock leaves the entries to it.
#[test]
fn drain_trash_deletes_staged_entries_once_the_lock_is_free() {
let temp = crate::testing::tempdir().unwrap();
let trash = temp.path().join("trash");
let staged = trash.join("repo.feature-branch-1700000000");
let foreign = trash.join("not-staged");
fs::create_dir_all(staged.join("node_modules/pkg")).unwrap();
fs::write(staged.join("node_modules/pkg/index.js"), "x").unwrap();
fs::create_dir_all(&foreign).unwrap();
fs::write(trash.join("stray-file-1700000000"), "a staged file").unwrap();
assert_eq!(staged_trash_entries(&trash).len(), 2);
assert!(!trash_drain_running(&trash));
let holder = fs::File::create(temp.path().join("trash.lock")).unwrap();
holder.lock().unwrap();
assert!(trash_drain_running(&trash));
drain_trash(&trash).unwrap();
assert!(staged.exists(), "the lock holder owns the deletion");
drop(holder);
// A child that a concurrent test forks while `holder` is open inherits
// the lock until it execs, so a drain can still find it held for an
// instant and leave the deletion to that phantom holder.
crate::testing::wait_for("a drain to delete the staged entries", || {
drain_trash(&trash).unwrap();
staged_trash_entries(&trash).is_empty()
});
assert!(foreign.exists());
assert!(staged_trash_entries(&temp.path().join("missing")).is_empty());
}
/// An entry the drain can't delete ends the drain rather than looping.
#[cfg(unix)]
#[test]
fn drain_trash_stops_at_an_undeletable_entry() {
use std::os::unix::fs::PermissionsExt;
let temp = crate::testing::tempdir().unwrap();
let trash = temp.path().join("trash");
fs::create_dir(&trash).unwrap();
fs::write(trash.join("stuck-1700000000"), "x").unwrap();
// Unlinking an entry needs write permission on the trash itself.
fs::set_permissions(&trash, fs::Permissions::from_mode(0o555)).unwrap();
drain_trash(&trash).unwrap();
fs::set_permissions(&trash, fs::Permissions::from_mode(0o755)).unwrap();
}
/// Same-basename worktrees need distinct staging paths. Test staging
/// directly: a prune batch may share one detached drain, so per-branch
/// cleanup logs do not prove whether each worktree was staged.
#[test]
fn stages_worktrees_sharing_a_basename() {
let mut test = TestRepo::with_initial_commit();
let parent = test.root_path().parent().unwrap().to_path_buf();
let worktrees = [
("one", parent.join("aaaa/repo")),
("two", parent.join("bbbb/repo")),
];
for (branch, path) in &worktrees {
test.add_worktree_at_path(branch, path);
}
let repo = Repository::at(test.root_path()).unwrap();
let mut staged_paths = Vec::new();
for (branch, path) in &worktrees {
let git_dir = repo.worktree_at(path).git_dir().unwrap();
let registration = git_dir.file_name().unwrap().to_string_lossy();
let staged = stage_worktree_removal(&repo, path, Some(branch), false)
.unwrap()
.expect("each worktree must stage successfully");
assert!(!path.exists());
assert!(staged.exists());
// Pin the registration prefix independently of the wall clock.
assert!(
staged
.file_name()
.unwrap()
.to_string_lossy()
.starts_with(&format!("{registration}-"))
);
staged_paths.push(staged);
}
assert_ne!(staged_paths[0], staged_paths[1]);
assert!(staged_paths.iter().all(|path| path.exists()));
}
/// A `git worktree lock` must stop the rename even when the caller skipped
/// `prepare_worktree_removal` (merge used to construct a plan by hand).
#[test]
fn stage_refuses_locked_worktree() {
let mut test = TestRepo::with_initial_commit();
let worktree_path = test.add_worktree("feature");
test.lock_worktree("feature", Some("keep"));
let repo = Repository::at(test.root_path()).unwrap();
let err =
stage_worktree_removal(&repo, &worktree_path, Some("feature"), false).unwrap_err();
assert!(
matches!(
err.downcast_ref::<GitError>(),
Some(GitError::WorktreeLocked { branch, reason, .. })
if branch == "feature" && reason.as_deref() == Some("keep")
),
"expected WorktreeLocked, got {err:?}"
);
assert!(
worktree_path.exists(),
"locked worktree must still be on disk"
);
}
/// `--force` waives dirt, not a lock — same as `git worktree remove --force`.
#[test]
fn stage_refuses_locked_worktree_even_with_force() {
let mut test = TestRepo::with_initial_commit();
let worktree_path = test.add_worktree("feature");
test.lock_worktree("feature", None);
let repo = Repository::at(test.root_path()).unwrap();
let err = stage_worktree_removal(&repo, &worktree_path, Some("feature"), true).unwrap_err();
match err.downcast_ref::<GitError>() {
Some(GitError::WorktreeLocked { reason: None, .. }) => {}
other => panic!("expected WorktreeLocked without a reason, got {other:?}"),
}
assert!(worktree_path.exists());
}
#[test]
fn nested_worktree_reads_fresh_topology() {
let mut test = TestRepo::with_initial_commit();
let source = test.add_worktree("source");
let repo = Repository::at(test.root_path()).unwrap();
// Warm the cache before adding another checkout: the guard must read
// topology after planning, independently of that cache.
repo.list_worktrees().unwrap();
let late = test.add_worktree_at_path("late", &source.join("late"));
assert_eq!(nested_worktree(&repo, &source).unwrap(), Some(late));
}
#[cfg(unix)]
#[test]
fn nested_worktree_resolves_symlinked_parent() {
let mut test = TestRepo::with_initial_commit();
let source = test.add_worktree("source");
let nested = test.add_worktree_at_path("nested", &source.join("nested"));
let alias = test.root_path().parent().unwrap().join("source-alias");
std::os::unix::fs::symlink(&source, &alias).unwrap();
let repo = Repository::at(test.root_path()).unwrap();
assert_eq!(nested_worktree(&repo, &alias).unwrap(), Some(nested));
}
#[test]
fn nested_worktree_skips_missing_checkout() {
let mut test = TestRepo::with_initial_commit();
let source = test.add_worktree("source");
let nested = test.add_worktree_at_path("nested", &source.join("nested"));
std::fs::rename(&nested, test.root_path().parent().unwrap().join("saved")).unwrap();
let repo = Repository::at(test.root_path()).unwrap();
assert_eq!(nested_worktree(&repo, &source).unwrap(), None);
}
#[cfg(unix)]
#[test]
fn nested_worktree_refuses_unresolvable_checkout() {
let mut test = TestRepo::with_initial_commit();
let source = test.add_worktree("source");
let nested = test.add_worktree_at_path("nested", &source.join("nested"));
let saved = test.root_path().parent().unwrap().join("saved");
std::fs::rename(&nested, &saved).unwrap();
// A symlink loop is an actual resolution error, not evidence that the
// registered checkout is absent. Refuse cleanup rather than skip it.
std::os::unix::fs::symlink(&nested, &nested).unwrap();
let repo = Repository::at(test.root_path()).unwrap();
let err = nested_worktree(&repo, &source).unwrap_err();
assert!(
err.to_string().contains("Failed to resolve worktree @"),
"{err:?}"
);
assert!(saved.join(".git").exists());
}
/// Registry serialization starts after the fast-path rename, so worktree
/// staging can overlap while metadata teardown remains exclusive.
#[test]
fn stages_worktree_before_waiting_for_registry_lock() {
let mut test = TestRepo::with_initial_commit();
let worktree_path = test.add_worktree("feature");
let repo = Repository::at(test.root_path()).unwrap();
let worker_repo = repo.clone();
let worker_path = worktree_path.clone();
let registry_guard = repo.worktree_registry_write();
let worker = std::thread::spawn(move || {
stage_worktree_removal(&worker_repo, &worker_path, Some("feature"), false)
});
let deadline = std::time::Instant::now() + Duration::from_secs(10);
while worktree_path.exists() && std::time::Instant::now() < deadline {
std::thread::sleep(Duration::from_millis(10));
}
let renamed_before_unlock = !worktree_path.exists();
drop(registry_guard);
let result = worker.join().expect("staging thread should not panic");
assert!(
renamed_before_unlock,
"worktree should be renamed before registry teardown acquires the lock; result: {result:?}"
);
assert!(
result.unwrap().is_some(),
"worktree should use the rename fast path"
);
}
/// When the branch tip moves between snapshot capture and the deletion
/// attempt, the atomic compare-and-swap rejects the delete and surfaces
/// `RetainedRaced` rather than dropping the new commits silently.
///
/// The setup mimics a hook (or any concurrent writer) that advances the
/// branch after the planner observed it as integrated: we capture refs
/// when `feature` is at the same commit as `main` (trivially integrated),
/// then move `feature` forward, then call `delete_branch_if_safe` with
/// the stale snapshot. Integration check still says "integrated" (the
/// snapshotted SHA is reachable from main), but CAS catches the live
/// tip having moved and refuses the delete.
#[test]
fn cas_rejects_delete_when_branch_advances() {
let test = TestRepo::with_initial_commit();
test.run_git(&["branch", "feature"]);
let repo = Repository::at(test.root_path()).unwrap();
// Snapshot captures `feature` at the initial commit (same as `main`).
let snapshot = repo.capture_refs().unwrap();
let original_sha = snapshot.local_branch("feature").unwrap().commit_sha.clone();
// Race: advance `feature` after the snapshot.
test.run_git(&["checkout", "feature"]);
std::fs::write(test.root_path().join("race.txt"), "boom\n").unwrap();
test.run_git(&["add", "race.txt"]);
test.run_git(&["commit", "-m", "post-snapshot advance"]);
test.run_git(&["checkout", "main"]);
let advanced_sha = test.git_output(&["rev-parse", "feature"]);
assert_ne!(
original_sha, advanced_sha,
"test setup: tip must have moved"
);
let result = delete_branch_if_safe(&repo, &snapshot, "feature", "main", false).unwrap();
assert!(
matches!(result.outcome, BranchDeletionOutcome::RetainedRaced),
"expected RetainedRaced, got a different outcome"
);
// Branch survives, still at the post-race SHA.
let live = test.git_output(&["rev-parse", "feature"]);
assert_eq!(live, advanced_sha, "branch must not be deleted nor reset");
}
/// Plain integrated case still deletes via CAS. Sanity check that the
/// new code path doesn't break the common case.
#[test]
fn cas_deletes_when_branch_unchanged() {
let test = TestRepo::with_initial_commit();
test.run_git(&["branch", "feature"]);
let repo = Repository::at(test.root_path()).unwrap();
let snapshot = repo.capture_refs().unwrap();
let result = delete_branch_if_safe(&repo, &snapshot, "feature", "main", false).unwrap();
assert!(
matches!(result.outcome, BranchDeletionOutcome::Integrated(_)),
"expected Integrated, got a different outcome"
);
// Ref should be gone.
let mut rev_parse = std::process::Command::new("git");
crate::testing::configure_git_cmd(&mut rev_parse);
let exit = rev_parse
.args(["rev-parse", "--verify", "--quiet", "refs/heads/feature"])
.current_dir(test.root_path())
.status()
.unwrap();
assert!(!exit.success(), "branch should have been deleted");
}
/// Deleting a branch drops its marker, so a later branch reusing the name
/// doesn't inherit it; a retained branch keeps its marker.
#[test]
fn deletion_clears_branch_marker() {
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
for branch in ["integrated", "forced", "unmerged"] {
test.run_git(&["branch", branch]);
repo.set_config(
&format!("worktrunk.state.{branch}.marker"),
r#"{"marker":"🤖","set_at":0}"#,
)
.unwrap();
}
test.run_git(&["checkout", "unmerged"]);
std::fs::write(test.root_path().join("work.txt"), "work\n").unwrap();
test.run_git(&["add", "work.txt"]);
test.run_git(&["commit", "-m", "unmerged work"]);
test.run_git(&["checkout", "main"]);
let snapshot = repo.capture_refs().unwrap();
for (branch, force) in [("integrated", false), ("forced", true), ("unmerged", false)] {
delete_branch_if_safe(&repo, &snapshot, branch, "main", force).unwrap();
}
let fresh = Repository::at(test.root_path()).unwrap();
assert_eq!(fresh.branch_marker("integrated"), None);
assert_eq!(fresh.branch_marker("forced"), None);
assert_eq!(fresh.branch_marker("unmerged").as_deref(), Some("🤖"));
}
/// Deleting `<name>.vars` leaves branch `<name>`'s var named `marker`,
/// which shares the key `worktrunk.state.<name>.vars.marker`.
#[test]
fn deletion_keeps_var_sharing_marker_key() {
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
test.run_git(&["branch", "feature.vars"]);
repo.set_config("worktrunk.state.feature.vars.marker", "plain value")
.unwrap();
let snapshot = repo.capture_refs().unwrap();
delete_branch_if_safe(&repo, &snapshot, "feature.vars", "main", true).unwrap();
let fresh = Repository::at(test.root_path()).unwrap();
assert_eq!(
fresh
.config_last("worktrunk.state.feature.vars.marker")
.unwrap()
.as_deref(),
Some("plain value")
);
}
/// A marker that can't be unset doesn't fail a deletion that already
/// happened; Git itself only warns when the locked config blocks its own
/// branch-section cleanup.
#[test]
fn deletion_survives_marker_unset_failure() {
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
test.run_git(&["branch", "doomed"]);
repo.set_config(
"worktrunk.state.doomed.marker",
r#"{"marker":"🤖","set_at":0}"#,
)
.unwrap();
let lock = test.root_path().join(".git/config.lock");
std::fs::write(&lock, "").unwrap();
let snapshot = repo.capture_refs().unwrap();
let result = delete_branch_if_safe(&repo, &snapshot, "doomed", "main", true).unwrap();
std::fs::remove_file(&lock).unwrap();
assert!(matches!(
result.outcome,
BranchDeletionOutcome::ForceDeleted
));
let fresh = Repository::at(test.root_path()).unwrap();
assert_eq!(fresh.branch_marker("doomed").as_deref(), Some("🤖"));
}
/// A packed-ref lock failure must preserve the branch and the original
/// Git error; an unchanged ref is not evidence of branch movement.
#[test]
fn cas_propagates_error_when_packed_refs_locked() {
let test = TestRepo::with_initial_commit();
test.run_git(&["branch", "feature"]);
test.run_git(&["pack-refs", "--all"]);
test.run_git(&["config", "core.packedRefsTimeout", "0"]);
let repo = Repository::at(test.root_path()).unwrap();
let snapshot = repo.capture_refs().unwrap();
let expected_sha = &snapshot.local_branch("feature").unwrap().commit_sha;
std::fs::write(repo.git_common_dir().join("packed-refs.lock"), "").unwrap();
let result = delete_branch_if_safe(&repo, &snapshot, "feature", "main", false);
let error = result.err().expect("lock failure must propagate");
let message = error.display_message();
assert!(message.contains("packed-refs.lock"), "{message}");
assert_eq!(test.git_output(&["rev-parse", "feature"]), *expected_sha);
}
/// A branch whose name starts with `-` must still force-delete: the
/// `git branch -D -- <name>` separator stops git from parsing `-x` as an
/// option. Created via `update-ref` since `git branch` rejects leading-dash
/// names.
#[test]
fn force_delete_handles_flag_like_branch_name() {
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
let head = repo.run_command(&["rev-parse", "HEAD"]).unwrap();
test.run_git(&["update-ref", "refs/heads/-x", head.trim()]);
let snapshot = repo.capture_refs().unwrap();
let result = delete_branch_if_safe(&repo, &snapshot, "-x", "main", true).unwrap();
assert!(
matches!(result.outcome, BranchDeletionOutcome::ForceDeleted),
"expected ForceDeleted, got a different outcome"
);
assert!(
repo.run_command(&["rev-parse", "--verify", "--quiet", "refs/heads/-x"])
.is_err(),
"flag-like branch should have been force-deleted"
);
}
/// ForceDelete remains a direct `git branch -D` operation. If topology
/// changes after planning, Git's own checked-out-branch protection rejects
/// it rather than the SafeDelete topology guard translating it into a
/// retained outcome.
#[test]
fn force_delete_uses_git_checkout_protection() {
let test = TestRepo::with_initial_commit();
test.create_branch("feature");
let repo = Repository::at(test.root_path()).unwrap();
let snapshot = repo.capture_refs().unwrap();
let checkout = test.home_path().join("repo.feature-force-race");
test.run_git(&["worktree", "add", checkout.to_str().unwrap(), "feature"]);
assert!(
delete_branch_if_safe(&repo, &snapshot, "feature", "main", true).is_err(),
"git branch -D must refuse a branch checked out after planning"
);
assert!(
repo.run_command(&["rev-parse", "--verify", "refs/heads/feature"])
.is_ok(),
"Git's refusal must preserve the branch"
);
}
/// A lock is the user's explicit protection for a temporarily absent
/// worktree. It must win even over a synthetic record that is also marked
/// prunable; an ordinary unlocked prunable record remains stale.
#[test]
fn locked_prunable_checkout_still_requires_retention() {
let mut worktree = WorktreeInfo {
path: PathBuf::from("/missing/feature"),
head: "0123456789abcdef".to_string(),
branch: Some("feature".to_string()),
bare: false,
detached: false,
locked: Some("detachable media".to_string()),
prunable: Some("gitdir file points to non-existent location".to_string()),
};
assert!(branch_checkout_requires_retention(&worktree, "feature"));
worktree.locked = None;
assert!(!branch_checkout_requires_retention(&worktree, "feature"));
}
/// When the branch ref vanishes between snapshot capture and the CAS
/// delete, `git update-ref` fails *and* the ref is already absent, so
/// the outcome is a real error (propagated) — distinct from the
/// `RetainedRaced` case where the ref moved but still exists.
#[test]
fn cas_propagates_error_when_ref_vanished() {
let test = TestRepo::with_initial_commit();
test.run_git(&["branch", "feature"]);
let repo = Repository::at(test.root_path()).unwrap();
// Snapshot captures `feature`, then it is deleted out-of-band.
let snapshot = repo.capture_refs().unwrap();
test.run_git(&["branch", "-D", "feature"]);
// Integration still reads "integrated" from the stale snapshot, the CAS
// update-ref fails, and rev-parse confirms the ref is gone → error.
let result = delete_branch_if_safe(&repo, &snapshot, "feature", "main", false);
assert!(
result.is_err(),
"expected a propagated error when the ref vanished, got Ok"
);
}
/// A branch created after the snapshot has no checked SHA. Even if a live
/// resolution finds it integrated, safe deletion must not force-delete it
/// without a compare-and-swap protecting a subsequent commit.
#[test]
fn retains_branch_when_snapshot_lacks_expected_sha() {
let test = TestRepo::with_initial_commit();
let repo = Repository::at(test.root_path()).unwrap();
// Capture refs BEFORE `feature` exists, so the snapshot carries no SHA
// for it.
let snapshot = repo.capture_refs().unwrap();
assert!(
snapshot.local_branch("feature").is_none(),
"test setup: snapshot must predate the branch"
);
// Create `feature` at main's commit → trivially integrated (same
// commit), resolvable live but missing from the stale snapshot.
test.run_git(&["branch", "feature"]);
let (_, reason) = repo
.integration_reason(&snapshot, "feature", "main")
.unwrap();
assert!(reason.is_some(), "the live branch must appear integrated");
let result = delete_branch_if_safe(&repo, &snapshot, "feature", "main", false);
let error = result.err().expect("missing checked SHA must fail closed");
assert!(
error.to_string().contains("absent from ref snapshot"),
"unexpected error: {error}"
);
assert_eq!(
test.git_output(&["rev-parse", "feature"]),
test.git_output(&["rev-parse", "main"])
);
}
#[test]
fn test_branch_deletion_outcome_matching() {
// Ensure the match patterns work correctly
let outcomes = [
(BranchDeletionOutcome::NotDeleted, false),
(
BranchDeletionOutcome::RetainedCheckedOut {
path: PathBuf::from("/tmp/feature"),
},
false,
),
(BranchDeletionOutcome::RetainedRaced, false),
(BranchDeletionOutcome::ForceDeleted, true),
(
BranchDeletionOutcome::Integrated(IntegrationReason::SameCommit),
true,
),
];
for (outcome, expected_deleted) in outcomes {
let deleted = matches!(
outcome,
BranchDeletionOutcome::ForceDeleted | BranchDeletionOutcome::Integrated(_)
);
assert_eq!(deleted, expected_deleted);
}
}
#[test]
fn test_branch_deletion_mode_from_flags() {
assert_eq!(
BranchDeletionMode::from_flags(false, false),
BranchDeletionMode::SafeDelete
);
assert_eq!(
BranchDeletionMode::from_flags(false, true),
BranchDeletionMode::ForceDelete
);
assert_eq!(
BranchDeletionMode::from_flags(true, false),
BranchDeletionMode::Keep
);
// keep takes precedence over force
assert_eq!(
BranchDeletionMode::from_flags(true, true),
BranchDeletionMode::Keep
);
}
#[test]
fn test_branch_deletion_mode_helpers() {
assert!(BranchDeletionMode::Keep.should_keep());
assert!(!BranchDeletionMode::SafeDelete.should_keep());
assert!(!BranchDeletionMode::ForceDelete.should_keep());
assert!(BranchDeletionMode::ForceDelete.is_force());
assert!(!BranchDeletionMode::SafeDelete.is_force());
assert!(!BranchDeletionMode::Keep.is_force());
}
#[test]
fn test_remove_options_default() {
let opts = RemoveOptions::default();
assert!(opts.branch.is_none());
assert_eq!(opts.deletion_mode, BranchDeletionMode::SafeDelete);
assert!(opts.target_branch.is_none());
assert!(!opts.force_worktree);
}
#[test]
fn test_generate_removing_path() {
let trash_dir = PathBuf::from("/some/path/.git/wt/trash");
let git_dir = PathBuf::from("/some/path/.git/worktrees/repo1");
let removing_path = generate_removing_path(&trash_dir, &git_dir);
// Format: <trash>/<registration>-<timestamp>
let name = removing_path.file_name().unwrap().to_string_lossy();
assert!(name.starts_with("repo1-"));
assert!(removing_path.starts_with(&trash_dir));
}
/// A linked worktree uses a `.git` *file* pointing at
/// `<common>/.git/worktrees/<name>`, not a `.git` directory. The fsmonitor
/// IPC socket the force-kill path resolves must land under that
/// per-worktree git dir, never under a hand-constructed `<path>/.git`.
#[test]
fn test_fsmonitor_socket_resolves_to_linked_worktree_git_dir() {
use crate::git::Repository;
let tmp = crate::testing::tempdir().unwrap();
let git = |dir: &Path| crate::testing::configure_git_env(Cmd::new("git")).current_dir(dir);
let main = tmp.path().join("repo");
std::fs::create_dir(&main).unwrap();
git(&main).args(["init", "-b", "main"]).run().unwrap();
git(&main)
.args(["commit", "--allow-empty", "-m", "init"])
.run()
.unwrap();
let linked = tmp.path().join("repo.feature");
git(&main)
.args(["worktree", "add", linked.to_str().unwrap(), "-b", "feature"])
.run()
.unwrap();
// The defining property of a linked worktree: `.git` is a file.
assert!(linked.join(".git").is_file());
let repo = Repository::at(&main).unwrap();
let wt = repo.worktree_at(&linked);
let git_dir = wt.git_dir().unwrap();
// git_dir points into the shared common dir's worktrees/ subtree,
// not the worktree's own directory.
assert!(
git_dir.ends_with("worktrees/repo.feature"),
"expected per-worktree git dir, got {}",
git_dir.display()
);
let socket = git_dir.join("fsmonitor--daemon.ipc");
assert!(
!socket.starts_with(&linked),
"socket must resolve via the .git file, not <worktree>/.git: {}",
socket.display()
);
// No daemon ever ran, so the socket is absent and the whole force-kill
// path is a no-op that returns cleanly.
assert!(!socket.exists());
stop_fsmonitor_daemon(&wt);
}
/// Fail-open contract: when the per-worktree git dir can't be resolved
/// (the path is not a git worktree), `stop_fsmonitor_daemon` logs and
/// returns without panicking and without attempting a force-kill.
#[test]
fn test_fsmonitor_stop_unresolvable_git_dir_is_noop() {
use crate::git::Repository;
let tmp = crate::testing::tempdir().unwrap();
let main = tmp.path().join("repo");
std::fs::create_dir(&main).unwrap();
crate::testing::configure_git_env(Cmd::new("git"))
.current_dir(&main)
.args(["init", "-b", "main"])
.run()
.unwrap();
let repo = Repository::at(&main).unwrap();
// A path that is not a git worktree: `git_dir()` errors.
let not_a_worktree = tmp.path().join("nope");
std::fs::create_dir(¬_a_worktree).unwrap();
let wt = repo.worktree_at(¬_a_worktree);
assert!(wt.git_dir().is_err(), "precondition: git dir unresolvable");
// Hits the git_dir() Err arm: log + early return, no panic.
stop_fsmonitor_daemon(&wt);
}
/// A socket file that no process holds: the force-kill path runs `lsof`,
/// resolves no owning PID, and is a clean no-op — nothing is signalled and
/// the path is left intact. Exercises the real `lsof` lookup without a
/// live daemon.
#[cfg(unix)]
#[test]
fn test_fsmonitor_force_kill_unheld_socket_is_noop() {
use crate::git::Repository;
let tmp = crate::testing::tempdir().unwrap();
let main = tmp.path().join("repo");
std::fs::create_dir(&main).unwrap();
crate::testing::configure_git_env(Cmd::new("git"))
.current_dir(&main)
.args(["init", "-b", "main"])
.run()
.unwrap();
let repo = Repository::at(&main).unwrap();
let wt = repo.worktree_at(&main);
let socket = wt.git_dir().unwrap().join("fsmonitor--daemon.ipc");
// Plant a regular file where the IPC socket would be. No process holds
// it, so `lsof` resolves no PID and nothing is signalled.
std::fs::write(&socket, b"").unwrap();
stop_fsmonitor_daemon(&wt);
assert!(socket.exists(), "no-op path must not delete the socket");
}
}