Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Worktree management operations for Repository.
use std::collections::HashSet;
use std::ffi::OsStr;
use std::path::{Path, PathBuf};
use std::sync::{LazyLock, Mutex};
use anyhow::Context as _;
use color_print::cformat;
use dunce::canonicalize;
use super::working_tree::{
operation_in_progress_at, path_to_logging_context, registration_worktree_path,
};
use super::{
GitError, InProgressOperation, Repository, ResolvedWorktree, Selector, WorktreeInfo,
is_valid_branch_name, normalize_selector, resolve_input_path,
};
use crate::git::{CommandError, PlumbingDiff, WorktreeId, finalize_worktrees, is_bare_repo_dir};
use crate::path::{format_path_for_display, paths_match};
use crate::shell_exec::Cmd;
use crate::styling::{eprintln, format_with_gutter, hint_message, warning_message};
/// List top-level entries remaining in a directory after a failed removal.
///
/// Returns None if the directory doesn't exist, can't be read, or is empty.
/// Entries are sorted, with directories suffixed with `/`.
fn list_remaining_entries(path: &Path) -> Option<Vec<String>> {
let mut entries: Vec<String> = std::fs::read_dir(path)
.ok()?
.filter_map(|e| {
let e = e.ok()?;
let name = e.file_name().to_string_lossy().into_owned();
if e.file_type().ok()?.is_dir() {
Some(format!("{name}/"))
} else {
Some(name)
}
})
.collect();
entries.sort();
(!entries.is_empty()).then_some(entries)
}
impl Repository {
/// List all worktrees for this repository.
///
/// Returns a list of worktrees with bare entries filtered out.
///
/// **Ordering:** Git lists the main worktree first. For normal repos, `[0]` is
/// the main worktree. For bare repos, the bare entry is filtered out, so `[0]`
/// is the first linked worktree (no semantic "main" exists).
///
/// Returns an empty slice for bare repos with no linked worktrees.
///
/// Cached on `RepoCache` after the first successful call; subsequent calls
/// return a reference into the cache. See the module-level `# Caching` docs
/// for the "no post-mutation reads through the cache" invariant.
pub fn list_worktrees(&self) -> anyhow::Result<&[WorktreeInfo]> {
self.cache
.worktrees
.get_or_try_init(|| {
let stdout = {
let _registry = self.worktree_registry_read();
self.run_command_bytes(&["worktree", "list", "--porcelain", "-z"])?
};
let raw_worktrees = WorktreeInfo::parse_porcelain_list_z(&stdout)?;
let mut worktrees: Vec<_> =
raw_worktrees.into_iter().filter(|wt| !wt.bare).collect();
// Main-worktree path correction.
//
// Git's `get_main_worktree()` computes the main worktree path by stripping
// a trailing `/.git` from the common dir. Two layouts have no such suffix,
// so git leaves the path unchanged and reports the git data directory as
// the "main worktree": submodules, whose common dir is `.git/modules/sub`,
// and `--separate-git-dir` repositories, whose common dir is wherever the
// user put the store. Git consults neither `core.worktree` nor its own
// `gitdir` backlink in this code path.
//
// We detect this by checking whether the first worktree's path equals
// git_common_dir (which never holds for normal repos, where git_common_dir
// is `.git` inside the worktree). When matched, we correct it using
// repo_path(), which resolves both layouts from the signals git does
// record.
//
// We fix this here rather than at each call site because list_worktrees()
// is the single point where worktree paths enter the system — all consumers
// (worktree_for_branch, resolve_worktree, etc.) depend on paths being
// working directories. If git fixes this upstream, the condition stops
// triggering.
if let Some(first) = worktrees.first_mut()
&& canonicalize(&first.path).ok().as_deref() == Some(self.git_common_dir())
{
first.path = self.repo_path()?.to_path_buf();
}
finalize_worktrees(self, &mut worktrees);
Ok(worktrees)
})
.map(Vec::as_slice)
}
/// Find the worktree path for a given branch, if one exists.
///
/// A branch normally maps to at most one worktree, but `git worktree add
/// --force <path> <branch>` bypasses git's "already used by worktree" guard
/// and lets the same branch live in several at once. Worktrunk never creates
/// that state; when it exists, this resolves to the first worktree git lists
/// (roughly creation order) and warns once per branch so the otherwise-silent
/// choice is visible. See `warn_duplicate_checkout`.
pub fn worktree_for_branch(&self, branch: &str) -> anyhow::Result<Option<PathBuf>> {
let worktrees = self.list_worktrees()?;
let paths = worktree_paths_for_branch(worktrees, branch);
if paths.len() > 1 {
warn_duplicate_checkout(branch, &paths);
}
Ok(paths.into_iter().next())
}
/// The worktree `branch` is checked out in, refusing one nothing can run in.
///
/// [`worktree_for_branch`](Self::worktree_for_branch) answers where git has
/// the worktree *registered*; this answers where a command can actually
/// work. The branch-first callers use it — `wt merge` and `wt step push`,
/// which look their target up by name. `wt switch` and
/// [`recover`](crate::git::recover) already hold a path by the time they
/// need the verdict, so they ask
/// [`worktree_is_unusable`](Self::worktree_is_unusable) directly; the
/// selector ladder asks neither, since resolution answers what the user
/// named rather than whether it can be worked in.
///
/// The verdict is [`worktree_is_unusable`](Self::worktree_is_unusable).
///
/// `Ok(None)` when the branch has no worktree at all — a normal answer,
/// and the caller's to interpret.
pub fn usable_worktree_for_branch(&self, branch: &str) -> anyhow::Result<Option<PathBuf>> {
let Some(path) = self.worktree_for_branch(branch)? else {
return Ok(None);
};
if self.worktree_is_unusable(&path)? {
return Err(GitError::worktree_missing(branch.to_string(), &path).into());
}
Ok(Some(path))
}
/// Whether nothing can run in the worktree registered at `path`.
///
/// Two independent ways for that to be true, and neither implies the other,
/// so the test is the union:
///
/// - The directory is not there. `Path::exists()` is the whole of this one.
/// - Git reports the registration as `prunable` — its gitdir pointer no
/// longer resolves. This is the case an existence probe misses, because a
/// directory deleted and *recreated* (an interrupted `wt switch`, an
/// `rm -rf` followed by a `mkdir`) is there while holding nothing.
///
/// `prunable` alone is not the wider test it looks like: git withholds the
/// attribute from a **locked** worktree even when the directory is gone,
/// because prunability is git's pruning *policy* and a lock means "don't
/// prune this". A locked worktree on an unmounted volume — the case
/// `prepare_worktree_removal`'s lock guard exists for — carries no
/// `prunable` line, so a `prunable`-only test reads it as healthy and lets
/// a command walk into a directory that is not there.
///
/// The `prunable` half costs a lookup rather than a fork:
/// [`list_worktrees`](Self::list_worktrees) has already parsed and cached
/// the listing, and a path absent from it contributes nothing — no
/// registration is not a broken one. The existence half still applies to
/// such a path, so an unregistered directory that is gone answers `true`.
/// No caller reaches that combination: all three take their path out of the
/// listing.
pub fn worktree_is_unusable(&self, path: &Path) -> anyhow::Result<bool> {
if !path.exists() {
return Ok(true);
}
Ok(self
.list_worktrees()?
.iter()
.any(|wt| paths_match(&wt.path, path) && wt.is_prunable()))
}
/// The "home" worktree — main worktree for normal repos, default branch worktree for bare.
///
/// Used as the default source for `copy-ignored` and the `{{ primary_worktree_path }}` template.
/// Returns `None` for bare repos when no worktree has the default branch.
pub fn primary_worktree(&self) -> anyhow::Result<Option<PathBuf>> {
if self.is_bare()? {
let Some(branch) = self.default_branch() else {
return Ok(None);
};
self.worktree_for_branch(&branch)
} else {
Ok(Some(self.repo_path()?.to_path_buf()))
}
}
/// Find the worktree at a given path, returning its branch if known.
///
/// Returns `Some((path, branch))` if a worktree exists at the path,
/// where `branch` is `None` for detached HEAD worktrees.
///
/// Uses symlink-aware comparison so a path that resolves to a worktree
/// through one or more symlinks still matches the worktree's recorded path.
pub fn worktree_at_path(
&self,
path: &Path,
) -> anyhow::Result<Option<(PathBuf, Option<String>)>> {
let worktrees = self.list_worktrees()?;
Ok(worktrees
.iter()
.find(|wt| paths_match(&wt.path, path))
.map(|wt| (wt.path.clone(), wt.branch.clone())))
}
/// Unregister the one stale worktree at `path`, as `git worktree prune`
/// would, leaving whatever remains of its directory in place.
///
/// Git tracks worktrees in `.git/worktrees/<id>/` and calls an entry
/// prunable once `<path>/.git` is gone. Usually the whole directory went —
/// deleted externally, or renamed into the trash by
/// [`stage_worktree_removal`](crate::git::remove::stage_worktree_removal) —
/// but a sweep that deletes idle files and keeps directories, like macOS's
/// `$TMPDIR` cleanup, takes only the `.git`. Either way the admin dir is
/// stale, and deleting it is all `git worktree prune` does to the entry.
///
/// # Why not a git command
///
/// No git command unregisters one prunable entry in both shapes.
/// `git worktree prune` takes no path (below), and `git worktree remove`
/// refuses an entry whose directory remains, `--force` included: its
/// validation wants `<path>/.git` unless the whole directory is gone. So
/// this reproduces git's prune for the one entry — its test, then its
/// deletion.
///
/// The test is git's own (`should_prune_worktree`): the entry is not
/// locked, and nothing is at the `.git` its `gitdir` file names. It runs
/// under the registry lock just before the deletion, because the caller's
/// `prunable` came from an earlier listing, and it refuses rather than
/// deletes when either half has changed since — a lock taken, or a
/// remounted volume that reconnected the worktree. Deleting a live
/// worktree's admin dir would strand its checkout. Only a definite absence
/// counts as nothing being at `.git`; one that can't be statted for another
/// reason keeps the entry, where git's own test would prune it.
///
/// # Why not `git worktree prune`
///
/// `git worktree prune` takes no path filter: it walks *every* entry and
/// unregisters each one whose directory it cannot find at that instant. A
/// worktree that is merely absent right now — an unmounted volume, a
/// dropped network mount, a half-finished `mv` — is indistinguishable from
/// a deleted one, so removing worktree A would also unregister bystander
/// B. B's committed work survives (refs and objects are shared) and its
/// files stay on disk, but its admin dir does not: the index, `ORIG_HEAD`,
/// the per-worktree reflog, `refs/worktree/*` and `refs/bisect/*`, and any
/// in-progress rebase or merge all go with it. `git worktree repair`
/// cannot rebuild them — it relinks an admin dir, it does not recreate
/// one. A detached entry loses more: its `HEAD` was the only ref holding
/// commits made there, which the next `git gc` may then delete. Naming
/// the target keeps a removal's blast radius equal to its intent.
///
/// # Concurrent calls
///
/// This deletion and [`Repository::remove_worktree`]'s `git worktree
/// remove` serialize with each other for the same repository. Naming one
/// entry bounds what a call *deletes*, not what others *read*: `git
/// worktree remove` and `git worktree list` enumerate *every* entry under
/// `.git/worktrees/` and read each one's files, so one overlapping this
/// deletion can read the entry mid-deletion and fail (`failed to read
/// …/commondir` / `Invalid path …/.git/worktrees/<id>`). That is Git's own
/// TOCTOU between the enumerator's `readdir` and its `open`. The
/// repository-scoped write lock closes the in-process window;
/// [`Repository::list_worktrees`] takes the matching read side. A `git
/// worktree list` in an *unrelated* process — outside wt's lock — remains
/// exposed; wt's serialization only covers its own removals.
///
/// Git also `rmdir`s `.git/worktrees` once its last entry goes. This
/// leaves the empty directory, which git reads as no linked worktrees.
pub fn prune_worktree_entry(&self, path: &Path) -> anyhow::Result<()> {
let display = format_path_for_display(path);
let _registry = self.worktree_registry_write();
let (registration, recorded) = self.registration_at(path)?;
if !definitely_absent(®istration.join("locked"))? {
anyhow::bail!("Worktree @ {display} is locked");
}
if !definitely_absent(&recorded.join(".git"))? {
anyhow::bail!("Worktree @ {display} is no longer stale; its .git exists");
}
std::fs::remove_dir_all(®istration).with_context(|| {
format!(
"Failed to delete {}",
format_path_for_display(®istration)
)
})
}
/// What unregistering the stale worktree at `path` would destroy that
/// nothing else holds: staged changes in its index, or a git operation
/// partway through. `None` when its registration holds neither.
///
/// [`prune_worktree_entry`](Self::prune_worktree_entry) deletes the
/// registration, and the index and any rebase, merge, cherry-pick, revert
/// or bisect state go with it. While the registration survives, `git
/// worktree repair <path>` reconnects the directory — recreated first, if
/// it went too — and all of that comes back; afterwards staged files
/// survive only as dangling blobs. So the stale-removal paths ask this
/// first and keep an entry that holds either, which is where they are
/// more careful than `git worktree prune`. Files in a directory that
/// remains stay on disk either way, and a registration with no index has
/// nothing staged.
pub fn stale_worktree_work(&self, path: &Path) -> anyhow::Result<Option<StaleWorktreeWork>> {
let (registration, _) = self.registration_at(path)?;
if let Some(operation) = operation_in_progress_at(®istration) {
return Ok(Some(StaleWorktreeWork::Operation(operation)));
}
if definitely_absent(®istration.join("index"))? {
return Ok(None);
}
// The registration is a git dir in its own right, so its index is read
// against its `HEAD` without the working tree git can no longer find.
// Both commands answer with exit 0 or 1; anything else is a failure.
let git = |args: &[&str]| -> anyhow::Result<(bool, String)> {
let mut all = vec![OsStr::new("--git-dir"), registration.as_os_str()];
all.extend(args.iter().map(OsStr::new));
let output = self
.with_object_store_env(
Cmd::new("git")
.args(all.iter().copied())
.context(path_to_logging_context(path))
.scrub_git_discovery_env(),
)
.run()?;
match output.status.code() {
Some(0 | 1) => Ok((
output.status.success(),
String::from_utf8_lossy(&output.stdout).trim().to_owned(),
)),
_ => Err(CommandError::from_failed_output("git", &all, &output).into()),
}
};
// An unborn `HEAD` compares against the empty tree, so everything in
// its index counts as staged.
let (born, head) = git(&["rev-parse", "--verify", "--quiet", "HEAD"])?;
let base = self.index_base_for(born.then_some(head))?;
// `--quiet` exits 1 when the index differs from the base.
let (unchanged, _) = git(&PlumbingDiff::Index.args(&["--cached", "--quiet", &base, "--"]))?;
Ok((!unchanged).then_some(StaleWorktreeWork::StagedChanges))
}
/// The registration `<common>/worktrees/<id>` whose `gitdir` names the
/// worktree at `path`, with the worktree path it records.
///
/// Unreadable siblings (an entry another process is deleting) are not
/// this one, so they are passed over rather than failing the lookup.
pub(crate) fn registration_at(&self, path: &Path) -> anyhow::Result<(PathBuf, PathBuf)> {
let registrations = self.git_common_dir().join("worktrees");
std::fs::read_dir(®istrations)
.with_context(|| format!("Failed to read {}", format_path_for_display(®istrations)))?
.filter_map(Result::ok)
.map(|entry| entry.path())
.find_map(|registration| {
let recorded = registration_worktree_path(®istration).ok()?;
paths_match(&recorded, path).then_some((registration, recorded))
})
.with_context(|| format!("No worktree registered @ {}", format_path_for_display(path)))
}
/// Remove a worktree at the specified path.
///
/// When `force` is true, passes `--force` to `git worktree remove`,
/// allowing removal even when the worktree contains untracked files
/// (like build artifacts such as `.vite/` or `node_modules/`).
///
/// When the worktree contains initialized submodules, git refuses removal
/// even for clean worktrees. This method detects that case up front and
/// adds `--force`, which is safe because the caller has already validated
/// worktree cleanliness via `ensure_clean()`.
///
/// # Why git requires `--force` for submodules
///
/// Git's `--force` flag on `worktree remove` bypasses two unrelated
/// protections under one flag: dirty working tree checks AND the
/// submodule structural check. We separate these concerns — our
/// `ensure_clean()` handles dirty state, and `--force`
/// handles the submodule restriction.
///
/// # TOCTOU note
///
/// Git checks for submodules *before* checking for dirty files, so when
/// we synthesize `--force` for a submodule worktree, git's own dirty
/// check is bypassed. To keep failing closed on a file modified after the
/// caller's `ensure_clean()`, this method re-runs `ensure_clean()` itself
/// immediately before the synthesized-force removal — restoring the
/// backstop git would otherwise have provided. (For an explicit
/// user-requested `force`, the user opted into destructive removal, so no
/// re-check.)
pub fn remove_worktree(&self, path: &std::path::Path, force: bool) -> anyhow::Result<()> {
let use_force = if force {
true
} else {
self.worktree_at(path).has_initialized_submodules()?
};
let mut args = vec![OsStr::new("worktree"), OsStr::new("remove")];
if use_force {
args.push(OsStr::new("--force"));
}
args.push(path.as_os_str());
// The synthesized-force cleanliness check and destructive command are
// one critical section. If this waited for another registry teardown
// after the check, a concurrent writer could dirty the worktree before
// `--force` bypassed Git's own dirty gate.
let _registry = self.worktree_registry_write();
if use_force && !force {
// Synthesized force (submodule worktree, not user-requested).
// `--force` will suppress git's dirty check, so re-validate
// cleanliness ourselves right before the destructive command —
// a file modified since the caller's check must still fail
// closed rather than be silently destroyed.
self.worktree_at(path).ensure_clean(
"remove worktree with submodules",
None,
/* force_hint */ true,
)?;
tracing::debug!("Using --force for worktree removal due to initialized submodules");
}
// Capture the display identity before Git may remove its `.git` entry.
let branch = self
.worktree_at(path)
.branch()?
.unwrap_or_else(|| crate::git::path_dir_name(path).to_string());
self.run_command(&args)
.map_err(|error| GitError::WorktreeRemovalFailed {
branch,
path: path.to_path_buf(),
error,
remaining_entries: list_remaining_entries(path),
})?;
Ok(())
}
/// Expand `@` / `-` / `^`, reporting whether `name` was one of them.
///
/// `None` means the token is not a shortcut and reaches the caller
/// untouched — the fact [`Selector`] carries as `names_a_path`, stated by
/// the step that would have done the rewriting rather than inferred
/// downstream by comparing this function's output against its input. The
/// two are not the same question: an expansion can legitimately return the
/// token it was given (a `-` history entry naming the branch you are on),
/// and any normalization applied around the call makes the comparison lie
/// outright.
fn expand_shortcut(&self, name: &str) -> anyhow::Result<Option<String>> {
let expanded = match name {
"@" => self.current_worktree().branch()?.ok_or_else(|| {
GitError::DetachedHead {
action: Some("resolve @ to current branch".into()),
worktree: None,
}
.into()
}),
"-" => {
// Read from worktrunk.history (recorded by wt switch operations)
self.switch_previous().ok_or_else(|| {
GitError::Other {
message: cformat!(
"No previous branch found in history; to see available worktrees, run <bold>wt list</>"
),
}
.into()
})
}
"^" => self.default_branch().ok_or_else(|| {
GitError::Other {
message: cformat!(
"Cannot determine default branch; specify the target explicitly, or to configure one, run <bold>wt config state default-branch set BRANCH</>"
),
}
.into()
}),
_ => return Ok(None),
};
expanded.map(Some)
}
/// Normalize and expand a token the user typed into the [`Selector`] the
/// resolvers work on.
///
/// The one place normalization happens for the worktree ladder — possible
/// only because `may_name_path` is set from whether `expand_shortcut`
/// fired, rather than from a string comparison this would corrupt.
pub fn expand_selector(&self, name: &str) -> anyhow::Result<Selector> {
let name = normalize_selector(name);
Ok(match self.expand_shortcut(name)? {
Some(token) => Selector::rewritten_to(token),
None => Selector::literal(name),
})
}
/// Resolve a worktree selector — the one place a token the user typed
/// becomes a worktree.
///
/// Every argument that names a worktree routes through here, so they all
/// accept the same vocabulary: the shortcuts, a branch name, and the path
/// of the worktree itself. wt addresses worktrees by branch (see the
/// "Worktree Model" section of `AGENTS.md`), so the branch is tried first
/// and a path only answers what a branch name cannot — a detached worktree,
/// or one of several checkouts of the same branch.
///
/// Resolution order:
/// 1. `@` — the current worktree, matched by path so detached HEAD
/// resolves; outside any worktree, the branch HEAD names, as below
/// 2. `-` — the worktree `wt switch` last left, by the path it recorded
/// (see [`switch_previous_worktree`](Self::switch_previous_worktree))
/// 3. `-` / `^` — the previous / default branch, then as a branch below
/// 4. a branch with a worktree
/// 5. a path naming a registered worktree — absolute, `~`-relative, or
/// relative to `-C` (see [`resolve_input_path`])
/// 6. otherwise the branch alone, which may or may not exist
///
/// A path that named no worktree lands in `BranchOnly` or
/// `NoWorktreeAtPath` — [`resolve_selector`](Self::resolve_selector)
/// decides which, once, so no reporting site has to.
///
/// # Returns
/// - `Worktree { path, branch }` — `branch` is `None` for a detached worktree
/// - `BranchOnly { branch }` when nothing is checked out under that name
/// - `NoWorktreeAtPath { path }` when the selector named a directory instead
///
/// A worktree git reports as *prunable* still resolves here. Resolution
/// answers "what did the user name", and `wt remove` names one precisely
/// in order to clean up its registration. Refusing to *work* in one is
/// [`usable_worktree_for_branch`](Self::usable_worktree_for_branch)'s job,
/// which the commands that go on to run there call instead.
pub fn resolve_worktree(&self, name: &str) -> anyhow::Result<ResolvedWorktree> {
// `@` and `-` resolve by path rather than by name, which is what lets
// them answer for a detached worktree — where the branch expansion
// `expand_selector` would apply has nothing to return.
let name = normalize_selector(name);
if name == "@" {
// `root()` falls back to the cwd itself outside a work tree, so
// only a registered worktree at that path counts. Compare
// canonical identities so alternate path spellings (for example
// macOS `/var` and `/private/var`) select one inventory entry
// without changing Git's registered path.
let current = self.current_worktree();
let path = current.root()?;
let current_id = WorktreeId::new(&path);
if let Some(wt) = self
.list_worktrees()?
.iter()
.find(|wt| wt.id() == current_id)
{
return Ok(ResolvedWorktree::worktree(path, wt.branch.clone()));
}
// Inside a work tree git no longer has registered at this path (a
// worktree moved without `git worktree repair`), `@` still means
// this directory, which holds no worktree wt can act on.
if current.prewarm_info()?.is_inside {
return Ok(ResolvedWorktree::NoWorktreeAtPath { path });
}
// Outside every work tree — a bare repo's directory, or a `.git`
// directory — `@` falls through to the branch HEAD names, as
// `expand_selector` reads it.
}
if name == "-"
&& let Some((path, branch)) = self.switch_previous_worktree()?
{
return Ok(ResolvedWorktree::worktree(path, branch));
}
self.resolve_selector(&self.expand_selector(name)?)
}
/// The worktree ladder itself: branch first, then path, then a verdict on
/// what the selector could have meant.
///
/// Split from [`resolve_worktree`](Self::resolve_worktree) for the callers
/// whose selector comes from somewhere other than the user's token — `wt
/// switch`, for a `pr:`/`mr:` branch or a stripped remote prefix — and
/// report that rewriting through the [`Selector`]. They used to
/// re-implement these three steps rather than expand into a shared one.
pub fn resolve_selector(&self, selector: &Selector) -> anyhow::Result<ResolvedWorktree> {
let token = selector.token();
if let Some(path) = self.worktree_for_branch(token)? {
return Ok(ResolvedWorktree::worktree(path, Some(token.to_string())));
}
// Both remaining steps are about the token as a path, so
// `names_a_path` gates them together: a rewritten token gets neither a
// worktree matched by path nor a verdict about a directory, since the
// user never typed it as a path.
if !selector.names_a_path() {
return Ok(ResolvedWorktree::branch_only(token.to_string()));
}
if let Some((path, wt_branch)) = self.worktree_at_input_path(token)? {
return Ok(ResolvedWorktree::worktree(path, wt_branch));
}
// Nothing matched, so say which of the two the selector was reaching
// for. Free for an ordinary branch name: `path_selector_directory`
// returns on `is_valid_branch_name` before touching the filesystem.
Ok(match self.path_selector_directory(token) {
Some(path) => ResolvedWorktree::NoWorktreeAtPath { path },
None => ResolvedWorktree::branch_only(token.to_string()),
})
}
/// The branch a selector names, erroring only when it names a detached
/// worktree.
///
/// [`resolve_worktree`](Self::resolve_worktree) for the arguments that want
/// a branch rather than a worktree — the `--branch` of the `wt config
/// state` commands, which key state by branch name, defaulting to `@`. A
/// branch with no worktree is a fine answer to those; a worktree named by
/// path that has no branch is not.
pub fn require_selected_branch(&self, name: &str, action: &str) -> anyhow::Result<String> {
match self.resolve_worktree(name)? {
ResolvedWorktree::Worktree {
branch: Some(branch),
..
} => Ok(branch),
ResolvedWorktree::BranchOnly { branch, .. } => Ok(branch),
// A path spelling can't be the branch the caller is about to key
// state by.
ResolvedWorktree::NoWorktreeAtPath { path } => {
Err(GitError::WorktreeNotFoundAtPath { path }.into())
}
// Name the detached worktree only when it isn't the one the
// command runs in, as `GitError::DetachedHead` asks.
ResolvedWorktree::Worktree {
path, branch: None, ..
} if self.is_current_worktree(&path)? => Err(GitError::DetachedHead {
action: Some(action.to_string()),
worktree: None,
}
.into()),
ResolvedWorktree::Worktree {
path, branch: None, ..
} => Err(GitError::DetachedHead {
action: Some(cformat!(
"{action} — <bold>{}</> is detached",
format_path_for_display(&path)
)),
worktree: Some(path),
}
.into()),
}
}
/// Whether `path` is the worktree this repository was discovered in.
fn is_current_worktree(&self, path: &Path) -> anyhow::Result<bool> {
Ok(WorktreeId::new(self.current_worktree().root()?) == WorktreeId::new(path))
}
/// This repository, rooted at the worktree at `path`.
///
/// Keeps `self`, discovered from the cwd and with the caches it has
/// already filled, when `path` is the worktree it was discovered in, so a
/// command acting on `@` there runs exactly as it would from the cwd.
/// Otherwise discovers the repository at `path`.
pub fn rooted_at(self, path: &Path) -> anyhow::Result<Self> {
if self.is_current_worktree(path)? {
Ok(self)
} else {
Self::at(path)
}
}
/// The worktree a selector names — its path, and its branch (`None` when
/// detached) — erroring when it names none.
///
/// [`resolve_worktree`](Self::resolve_worktree) for the commands that need a
/// worktree to operate in rather than a branch to reason about. A branch
/// with no checkout and a name matching nothing at all are the same answer
/// to them. The branch comes back with the path so a caller that needs
/// both uses the pair resolution found, rather than looking one up from
/// the other: a branch checked out twice maps back to the wrong path.
/// A selector matching nothing at all is reported as such, rather than as a
/// branch without a worktree: `wt switch <the selector>` creates a worktree
/// only when the branch exists, so offering it for a mistyped path would
/// just fail again.
pub fn require_worktree(&self, name: &str) -> anyhow::Result<(PathBuf, Option<String>)> {
match self.resolve_worktree(name)? {
ResolvedWorktree::Worktree { path, branch, .. } => Ok((path, branch)),
ResolvedWorktree::BranchOnly { branch, .. } => Err(self.no_worktree_error(branch)),
ResolvedWorktree::NoWorktreeAtPath { path } => {
Err(GitError::WorktreeNotFoundAtPath { path }.into())
}
}
}
/// The directory a selector names, when it names one holding no worktree —
/// the skeleton an interrupted create or remove leaves behind.
///
/// Every argument naming a worktree is tried as a branch first and as a
/// path second, so each place that reports "no such thing" has to say which
/// of the two it was looking for. Answering that takes all four tests
/// below, and no three of them are enough:
///
/// - Git could never accept the selector as a branch name, so branch-first
/// never had a candidate. Without this, revision syntax reports as a
/// path: `~`, `^`, `:` and `@{` are ordinary vocabulary for naming a
/// commit as well as characters no branch name may hold.
/// - A directory is there to name, which is what makes "the user meant a
/// path" more than a guess. Without this, a name shadows a branch:
/// `wt remove docs` means the branch even when `docs/` sits beside it.
/// - No worktree of this repository is registered there, which is half of
/// what the error asserts. A detached worktree is reachable by its path
/// and by nothing else, so without this the message contradicts the
/// `wt list` its hint points at. The check is here rather than left to
/// callers because a caller cannot be relied on to have made it:
/// `resolve_worktree` skips the path lookup whenever a shortcut rewrote
/// the argument, so `-` expanding to a worktree's path arrives having
/// matched nothing.
/// - Nothing there claims to be a git directory, which is the other half:
/// `list_worktrees` covers only *this* repository, and worktrunk gathers
/// every repo and every worktree into one parent, so a sibling's live
/// checkout is one `../` away from any command. Calling one "not a
/// worktree" reads as an invitation to delete it, and it may hold
/// uncommitted work or the only copy of an object. A skeleton is what an
/// interrupted create or remove leaves, which holds no git data at all
/// (see `holds_git_data`).
///
/// `None` when any test fails, leaving the selector to be reported as a
/// branch. The verdict reaches callers as
/// [`ResolvedWorktree::NoWorktreeAtPath`] — this is
/// [`resolve_selector`](Self::resolve_selector)'s last step, and the only
/// caller that is not itself assembling the ladder is
/// [`require_target_branch`](Self::require_target_branch), whose target
/// vocabulary is wider than a worktree selector's.
///
/// The path is reported as the selector spells it, resolved against `-C`
/// but not otherwise tidied — so a `-C` base and a `./`-prefixed selector
/// join to a visible `/./`. Cosmetic, and Unix-only: rendering runs through
/// `format_path_for_display` and so through `path_slash`'s
/// `to_slash_lossy`, which is `to_string_lossy` verbatim there but rebuilds
/// the string from `Path::components()` on Windows, collapsing an interior
/// `/./`.
///
/// A trailing separator never reaches here: [`normalize_selector`] strips
/// it before resolution, so `docs/` and `docs` are one selector and both
/// find the branch.
pub fn path_selector_directory(&self, selector: &str) -> Option<PathBuf> {
if is_valid_branch_name(selector) {
return None;
}
let path = resolve_input_path(selector);
if !path.is_dir() {
return None;
}
// A failed listing says nothing about what is registered, so it counts
// against the claim exactly as a match does.
if !matches!(self.worktree_at_path(&path), Ok(None)) {
return None;
}
if holds_git_data(&path) {
return None;
}
Some(path)
}
/// The error for a selector that resolved to a branch with no checkout.
///
/// The directory case never arrives here — `resolve_selector` has already
/// separated it out — so this only has to choose between "the branch has no
/// worktree" and "nothing answers to this name at all".
fn no_worktree_error(&self, branch: String) -> anyhow::Error {
match self.branch(&branch).exists_locally() {
Ok(true) => GitError::WorktreeNotFound { branch }.into(),
// A ref lookup that fails says nothing about the branch, so fall
// back to the message that claims less.
_ => GitError::WorktreeSelectorNotFound { selector: branch }.into(),
}
}
/// The worktree a user-supplied token names by path, if it names one.
///
/// The path half of [`resolve_worktree`](Self::resolve_worktree), split out
/// for arguments that want a branch rather than a worktree — a merge target,
/// a state key. Resolving the token is the whole point: it goes through
/// [`resolve_input_path`] here so no call site
/// has to remember that a relative path answers to `-C` and a leading `~` to
/// the home directory.
///
/// Branch-first is the rule everywhere, so callers reach for this only after
/// a branch or ref lookup has already come up empty. `branch` is `None` for
/// a detached worktree.
pub fn worktree_at_input_path(
&self,
name: &str,
) -> anyhow::Result<Option<(PathBuf, Option<String>)>> {
self.worktree_at_path(&resolve_input_path(name))
}
/// Find the "home" path - where to cd when leaving a worktree.
///
/// Returns the primary worktree if it exists, otherwise the repo root.
/// - Normal repos: the main worktree (repo root)
/// - Bare repos: the default branch's worktree, or the bare repo directory
pub fn home_path(&self) -> anyhow::Result<PathBuf> {
self.primary_worktree()?
.map_or_else(|| self.repo_path().map(|p| p.to_path_buf()), Ok)
}
}
/// What a stale worktree's registration holds that unregistering it would
/// destroy — see [`Repository::stale_worktree_work`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StaleWorktreeWork {
/// The index differs from `HEAD`.
StagedChanges,
/// A git operation is partway through.
Operation(InProgressOperation),
}
/// Whether nothing is at `path`: `NotFound`, or `NotADirectory` where a parent
/// became a file. Any other error is returned, so a caller deciding whether to
/// delete keeps what it could not check.
fn definitely_absent(path: &Path) -> anyhow::Result<bool> {
match std::fs::symlink_metadata(path) {
Ok(_) => Ok(false),
Err(e) => match e.kind() {
std::io::ErrorKind::NotFound | std::io::ErrorKind::NotADirectory => Ok(true),
_ => Err(anyhow::Error::new(e)
.context(format!("Failed to check {}", format_path_for_display(path)))),
},
}
}
/// Whether `path` is a directory git would find data in — somebody's checkout
/// or repository, rather than a leftover skeleton.
///
/// Two shapes, because a repository is not always inside a working tree:
/// a worktree and a non-bare repo carry a `.git` (a file for the first, a
/// directory for the second), while a bare repo *is* the git directory and so
/// carries none. The second is the one worth spelling out — under worktrunk's
/// bare layout the repository sits among the worktrees it serves, one `../`
/// from any command, and it holds every object.
///
/// The bare test is [`is_bare_repo_dir`], and its shallowness is what this
/// caller wants: the answer decides whether to *withhold* a claim, so a false
/// positive costs a vaguer message and a false negative costs a wrong one.
///
/// Which is why absence has to be established rather than assumed. `Path::exists`
/// answers `false` for every error alike, so a `.git` that cannot be statted —
/// a clone the process may not traverse, a symlink whose target is gone —
/// would read as "no git data" and the message would tell someone their live
/// checkout is theirs to delete. Only a definite `NotFound` counts as nothing
/// being there; anything else keeps the claim withheld.
///
/// A `.git` whose pointer dangles counts too, and following it to check would
/// be the wrong refinement. Two very different directories carry a dangling
/// `.git`: a `git worktree add` that died after writing it, holding nothing
/// else; and a worktree a repo-wide prune unregistered while its volume was
/// unmounted, holding all its files and any uncommitted work (the bystander
/// case [`Repository::prune_worktree_entry`] documents). The pointer cannot
/// tell them apart, so resolving it would license "this is a leftover" over the
/// second.
fn holds_git_data(path: &Path) -> bool {
// `symlink_metadata` reports on the entry itself, so a symlink counts even
// when its target is gone, and it surfaces a traversal error instead of
// swallowing it.
let no_git_entry = matches!(
std::fs::symlink_metadata(path.join(".git")),
Err(e) if e.kind() == std::io::ErrorKind::NotFound
);
if !no_git_entry {
return true;
}
// Reached only when that probe succeeded in saying "nothing there", so the
// directory is readable and the bare shape can be read plainly.
is_bare_repo_dir(path)
}
/// Paths of every worktree checked out on `branch`, in git's listing order.
///
/// At most one under normal use; more than one only when the user ran
/// `git worktree add --force <path> <branch>`, which bypasses git's
/// "already used by worktree" guard. Worktrunk never creates that state.
pub(crate) fn worktree_paths_for_branch(worktrees: &[WorktreeInfo], branch: &str) -> Vec<PathBuf> {
worktrees
.iter()
.filter(|wt| wt.branch.as_deref() == Some(branch))
.map(|wt| wt.path.clone())
.collect()
}
/// Every branch checked out in more than one worktree.
///
/// The all-at-once counterpart to `worktree_paths_for_branch`, for callers
/// classifying the whole list rather than resolving one branch — `wt list`
/// flags each affected row with `⚐` so the ambiguity is visible before a
/// command resolves the branch and warns.
pub fn duplicated_branches(worktrees: &[WorktreeInfo]) -> HashSet<&str> {
let mut seen = HashSet::new();
let mut duplicated = HashSet::new();
for branch in worktrees.iter().filter_map(|wt| wt.branch.as_deref()) {
if !seen.insert(branch) {
duplicated.insert(branch);
}
}
duplicated
}
/// Warn once per process that `branch` resolves ambiguously across worktrees.
///
/// Worktrunk addresses worktrees by branch name and resolves an ambiguous
/// branch to the first worktree git lists, leaving the others reachable only by
/// path. The warning surfaces that otherwise-silent choice — naming every
/// path — without changing which worktree is used. Deduplicated per branch so
/// a command that resolves the same branch repeatedly (the picker, `wt list`)
/// warns only once.
///
/// Called only from `worktree_for_branch` with `paths.len() > 1`, so `paths[1..]`
/// names at least one shadowed worktree.
fn warn_duplicate_checkout(branch: &str, paths: &[PathBuf]) {
static WARNED: LazyLock<Mutex<HashSet<String>>> = LazyLock::new(|| Mutex::new(HashSet::new()));
// A poisoned set of already-warned branches never justifies aborting; recover it.
let is_new = WARNED
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
.insert(branch.to_string());
if is_new {
let listing = paths
.iter()
.map(|p| format_path_for_display(p))
.collect::<Vec<_>>()
.join("\n");
eprintln!(
"{}",
warning_message(cformat!(
"Branch <bold>{branch}</> is checked out in {} worktrees; wt uses the first:",
paths.len()
))
);
eprintln!("{}", format_with_gutter(&listing, None));
// Name every shadowed worktree so removing them all is actionable; with a
// single extra (the common case) this is one hint. `wt remove <path>`
// removes exactly the worktree named and retains the branch the others
// still hold, so it's safe to suggest for a duplicate.
for extra in &paths[1..] {
// Already shell-ready; `suggest_command` would escape it again.
let cmd = format!("wt remove {}", format_path_for_display(extra));
eprintln!(
"{}",
hint_message(cformat!("To drop a duplicate, run <underline>{cmd}</>"))
);
}
}
}