Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Worktree switch operations.
//!
//! Planning and executing worktree switches, plus [`SwitchPipeline`] — the
//! full switch sequence (bare-repo fix-up, hooks, approval, execution, output)
//! shared by the `wt switch` argument path and the interactive picker.
use std::path::{Path, PathBuf};
use crate::display::format_relative_time_short;
use anyhow::{Context, bail};
use color_print::cformat;
use dunce::canonicalize;
use normalize_path::NormalizePath;
use serde::Serialize;
use worktrunk::HookType;
use worktrunk::config::{
HookSource, UserConfig, ValidationScope, VarScope, referenced_vars_for_templates,
template_references_var, validate_template,
};
use worktrunk::git::remote_ref::{self, RemoteRefInfo, parse_ref_url};
use worktrunk::git::{
ErrorExt, ForgeKind, GitError, GitRemoteUrl, RefType, Repository, ResolvedWorktree, Selector,
SwitchSuggestionCtx, WorktreeId, branch_tracks_ref, current_or_recover, resolve_input_path,
};
use worktrunk::path::{canonicalize_with_parents, format_path_for_display};
use worktrunk::shell_exec::{ShellEscapeMode, shell_cwd};
use worktrunk::styling::{
eprintln, format_with_gutter, hint_message, info_message, progress_message, suggest_command,
warning_message,
};
use worktrunk::utils::escape_controls;
use super::resolve::{compute_worktree_path, offer_bare_repo_worktree_path_fix};
use super::types::{CreationMethod, RefIdentity, SwitchBranchInfo, SwitchPlan, SwitchResult};
use crate::cli::{SwitchArgs, SwitchFormat};
use crate::commands::backup::back_up_clobbered_path_now;
use crate::commands::command_approval::approve_hooks;
use crate::commands::command_executor::FailureStrategy;
use crate::commands::command_executor::{CommandContext, build_hook_context};
use crate::commands::flag_pair;
use crate::commands::hook_plan::{ApprovedHookPlan, HookPlanBuilder, register_planned};
use crate::commands::hooks::{HookAnnouncer, execute_hook};
use crate::commands::template_vars::TemplateVars;
use crate::output::{
CommandFailure, CommandResult, execute_user_command, handle_switch_output,
is_shell_integration_active, print_json, prompt_shell_integration,
};
/// A `pr:N` / `mr:N` argument resolved through the forge.
struct ResolvedTarget {
/// The PR/MR's branch, under the local name it is or will be checked out as.
selector: Selector,
/// How to create the worktree
method: CreationMethod,
/// The PR/MR itself, for the `pr_number` / `pr_url` hook variables.
/// Independent of `method`: a same-repo PR resolves to
/// `CreationMethod::Regular` and still has an identity.
ref_identity: RefIdentity,
}
/// The switch argument resolved to its destination.
///
/// [`SwitchPipeline::run`] resolves it before the `pre-switch` hooks, so their
/// variables describe the destination, and hands the same value to
/// [`plan_switch`]. A hook is arbitrary code, though, and may fetch or create
/// the branch the argument names, so when one ran the pipeline locates the
/// argument again through the same [`SwitchTarget::locate`], on a fresh
/// [`Repository`]. The forge is asked about `pr:N` / `mr:N` only the first
/// time. How to create a new worktree — `--base` and the `--create` checks —
/// is left to `plan_switch` for the same reason.
struct SwitchTarget {
destination: SwitchDestination,
/// The forge's answer for `pr:N` / `mr:N`.
remote_ref: Option<ResolvedTarget>,
}
enum SwitchDestination {
/// A worktree the argument names; `branch` is `None` when it is detached,
/// which only a path can name.
Existing {
path: PathBuf,
branch: Option<String>,
},
/// A branch with no worktree, or one `--create` is about to make.
New { branch: String },
}
impl SwitchTarget {
/// Resolve `identifier`, reaching the forge for `pr:N` / `mr:N`.
fn resolve(
repo: &Repository,
identifier: &str,
create: bool,
base: Option<&str>,
) -> anyhow::Result<Self> {
let remote_ref = resolve_ref_shortcut_target(repo, identifier, create, base)?;
Self::locate(repo, identifier, create, remote_ref)
}
/// Find what `identifier` names in `repo` as it is now, given the forge's
/// answer when the argument was `pr:N` / `mr:N`.
fn locate(
repo: &Repository,
identifier: &str,
create: bool,
remote_ref: Option<ResolvedTarget>,
) -> anyhow::Result<Self> {
let resolved = match &remote_ref {
Some(target) => repo.resolve_selector(&target.selector)?,
// Under `--create` the argument names a branch that does not exist
// yet: not a worktree, a path, or a remote-tracking name.
None if create => {
let branch = repo
.expand_selector(identifier)
.context("Failed to resolve branch name")?
.token()
.to_string();
return Ok(Self {
destination: SwitchDestination::New { branch },
remote_ref,
});
}
None => resolve_switch_argument(repo, identifier)?,
};
let destination = match resolved {
ResolvedWorktree::Worktree { path, branch, .. } => {
SwitchDestination::Existing { path, branch }
}
ResolvedWorktree::BranchOnly { branch, .. } => SwitchDestination::New { branch },
// Nothing is registered there, and a path is all the argument
// could have been, so there is no destination to switch to,
// create, or describe to the hooks.
ResolvedWorktree::NoWorktreeAtPath { path } => {
return Err(GitError::WorktreeNotFoundAtPath { path }.into());
}
};
Ok(Self {
destination,
remote_ref,
})
}
/// The branch the switch lands on. `None` for a detached worktree.
fn branch(&self) -> Option<&str> {
match &self.destination {
SwitchDestination::Existing { branch, .. } => branch.as_deref(),
SwitchDestination::New { branch } => Some(branch),
}
}
fn ref_identity(&self) -> Option<&RefIdentity> {
self.remote_ref.as_ref().map(|target| &target.ref_identity)
}
}
/// Resolve a `wt switch` argument other than `pr:N` / `mr:N` or a `--create`
/// name.
///
/// [`Repository::resolve_worktree`] — the ladder every worktree argument goes
/// through, `@` resolving by path — plus one rewrite: a remote-tracking name
/// such as `origin/feature`, which the picker passes for a remote branch,
/// names the local branch `feature` unless a local branch is literally called
/// `origin/feature`.
fn resolve_switch_argument(
repo: &Repository,
identifier: &str,
) -> anyhow::Result<ResolvedWorktree> {
let resolved = repo
.resolve_worktree(identifier)
.context("Failed to resolve branch name")?;
if let ResolvedWorktree::BranchOnly { branch, .. } = &resolved
&& !repo.branch(branch).exists_locally()?
&& let Some(local_name) = repo.strip_remote_prefix(branch)
{
// A rewrite like any other: `origin/foo` may have been a path the user
// typed, but `foo` is one nobody did.
return repo.resolve_selector(&Selector::rewritten_to(local_name));
}
Ok(resolved)
}
/// Format PR/MR context for gutter display after fetching.
///
/// Returns two lines for gutter formatting:
/// ```text
/// ┃ Fix authentication bug in login flow (#101)
/// ┃ by @alice · open · feature-auth · https://github.com/owner/repo/pull/101
/// ```
fn format_ref_context(info: &RemoteRefInfo) -> String {
let mut status_parts = vec![format!("by @{}", info.author), info.state.clone()];
if info.draft {
status_parts.push("draft".to_string());
}
status_parts.push(info.source_ref());
let status_line = status_parts.join(" · ");
let status_line = escape_controls(&status_line);
cformat!(
"<bold>{}</> ({}{})\n{status_line} · <bright-black>{}</>",
escape_controls(&info.title),
info.ref_type().symbol(),
info.number,
escape_controls(&info.url)
)
}
/// Choose which forge should handle `pr:<number>` resolution.
///
/// Priority:
/// 1. The configured `forge.platform` (`github` / `gitea` / `azure-devops`) —
/// the repository's own, else a matching user-config `[projects."…"]`
/// entry, via [`Repository::configured_forge_platform`]
/// 2. Every configured raw remote, in GitHub > Gitea > Azure DevOps > GitLab
/// order. [`ForgeKind::from_host`] classifies exact forge labels and Azure
/// DevOps service-domain suffixes.
/// 3. CLI auth lookup — if `tea` has a login for this host but `gh` does
/// not, pick Gitea; otherwise default to GitHub
///
/// The default-to-GitHub fall-through means a self-hosted Gitea on a branded
/// host (e.g. `git.example.com`) without `tea login add` will see a single
/// GitHub error with a hint to set `forge.platform = "gitea"`.
fn choose_pr_forge(repo: &Repository) -> anyhow::Result<ForgeKind> {
if let Some(platform_raw) = repo.configured_forge_platform() {
match platform_raw.to_ascii_lowercase().parse::<ForgeKind>() {
Ok(ForgeKind::GitLab) => {
bail!("forge.platform is set to gitlab; use mr:<number> instead of pr:<number>")
}
Ok(platform) => return Ok(platform),
Err(_) => bail!(
"Invalid forge.platform value `{platform_raw}` (from `[forge]` in project \
config or a `[projects]` entry in user config); \
expected one of: github, gitlab, gitea, azure-devops"
),
}
}
// GitHub still wins in mixed-remote setups (preserves pre-Gitea/Azure
// behaviour for repos that grew a mirror later). Scan every remote so a
// non-primary `origin` doesn't hide a GitHub mirror.
let all_parsed: Vec<_> = repo
.all_remote_urls()
.into_iter()
.filter_map(|(_, url)| GitRemoteUrl::parse(&url))
.collect();
let has_forge = |forge| all_parsed.iter().any(|url| url.forge_kind() == Some(forge));
if has_forge(ForgeKind::GitHub) {
return Ok(ForgeKind::GitHub);
}
if has_forge(ForgeKind::Gitea) {
return Ok(ForgeKind::Gitea);
}
if has_forge(ForgeKind::AzureDevOps) {
return Ok(ForgeKind::AzureDevOps);
}
if has_forge(ForgeKind::GitLab) {
bail!("Detected GitLab remote; use mr:<number> instead of pr:<number>")
}
// No recognisable forge remote. Use the primary remote (raw URL — `insteadOf`
// rewrites are for git transport and may not reflect the real forge host)
// to ask the CLIs which one is configured for this host. If only `tea` has a
// login, pick Gitea; otherwise default to GitHub (the common case, and the
// one users get useful errors from when nothing is set up).
let Some(host) = repo
.primary_remote()
.ok()
.and_then(|remote| repo.remote_url(&remote))
.and_then(|url| GitRemoteUrl::parse(&url))
.map(|u| u.host().to_string())
else {
return Ok(ForgeKind::GitHub);
};
if remote_ref::gitea::is_authed_for(&host)? && !remote_ref::github::is_authed_for(&host) {
Ok(ForgeKind::Gitea)
} else {
Ok(ForgeKind::GitHub)
}
}
/// Fetch PR/MR info while showing a "still waiting" status.
///
/// The forge CLI captures its output and can stall on a slow network, so
/// without feedback the command looks frozen. The watchdog clears
/// before the caller prints the resolved ref context. No command gutter — the
/// host CLI invocation isn't readily available here, and the status line alone
/// is the signal.
fn fetch_ref_info(
forge: ForgeKind,
number: u32,
repo: &Repository,
) -> anyhow::Result<RemoteRefInfo> {
let _watchdog = worktrunk::progress::Watchdog::start(
&format!("the {} lookup", forge.ref_type().name()),
None,
);
remote_ref::fetch_info(forge, number, repo)
}
/// Resolve a remote ref (PR or MR) through the selected forge.
fn resolve_remote_ref(
repo: &Repository,
forge: ForgeKind,
number: u32,
create: bool,
) -> anyhow::Result<ResolvedTarget> {
let ref_type = forge.ref_type();
let symbol = ref_type.symbol();
// Fetch ref info through the forge CLI.
eprintln!(
"{}",
progress_message(cformat!("Fetching {} {symbol}{number}...", ref_type.name()))
);
let info = fetch_ref_info(forge, number, repo)?;
// Display context with URL (as gutter under fetch progress)
eprintln!("{}", format_with_gutter(&format_ref_context(&info), None));
// --create is invalid with pr:/mr: syntax (check after fetch to show branch name)
if create {
return Err(GitError::RefCreateConflict {
ref_type,
number,
branch: info.source_branch.clone(),
}
.into());
}
let (selector, method) = if info.is_cross_repo {
resolve_fork_ref(repo, forge, number, &info)?
} else {
// Same-repo ref: fetch the branch to ensure remote tracking refs exist
fetch_same_repo_branch(repo, &info)?;
(
Selector::rewritten_to(info.source_branch),
CreationMethod::Regular {
create_branch: false,
base_branch: None,
base_pr_upstream: None,
},
)
};
Ok(ResolvedTarget {
selector,
method,
ref_identity: RefIdentity {
number,
url: info.url,
},
})
}
/// Resolve a fork (cross-repo) PR/MR.
fn resolve_fork_ref(
repo: &Repository,
forge: ForgeKind,
number: u32,
info: &RemoteRefInfo,
) -> anyhow::Result<(Selector, CreationMethod)> {
let ref_type = forge.ref_type();
let repo_root = repo.repo_path()?;
let local_branch = info.source_branch.clone();
let tracking_ref = remote_ref::tracking_ref(forge, number);
let expected_remote = match remote_ref::find_remote(repo, info) {
Ok(remote) => Some(remote),
Err(e) => {
tracing::debug!(name = %ref_type.name(), error = %e, "Could not resolve remote for {}: {e:#}", ref_type.name());
None
}
};
// Check if branch already exists and is tracking this ref
if let Some(tracks_this) = branch_tracks_ref(
repo_root,
&local_branch,
&tracking_ref,
expected_remote.as_deref(),
) {
if tracks_this {
eprintln!(
"{}",
info_message(cformat!(
"Branch <bold>{local_branch}</> already configured for {}",
ref_type.display(number)
))
);
return Ok((
Selector::rewritten_to(local_branch),
CreationMethod::Regular {
create_branch: false,
base_branch: None,
base_pr_upstream: None,
},
));
}
// GitLab defers project URL lookup until a new branch is needed.
let mut prefixed_info = info.clone();
if forge == ForgeKind::GitLab {
let urls =
worktrunk::git::remote_ref::gitlab::fetch_gitlab_project_urls(info, repo_root)?;
prefixed_info.fork_push_url = urls.fork_push_url;
}
// A conflicting branch uses a fetch-only prefixed name on every forge.
if let Some(prefixed) = prefixed_info.prefixed_local_branch_name() {
if let Some(prefixed_tracks) = branch_tracks_ref(
repo_root,
&prefixed,
&tracking_ref,
expected_remote.as_deref(),
) {
if prefixed_tracks {
eprintln!(
"{}",
info_message(cformat!(
"Branch <bold>{prefixed}</> already configured for {}",
ref_type.display(number)
))
);
return Ok((
Selector::rewritten_to(prefixed),
CreationMethod::Regular {
create_branch: false,
base_branch: None,
base_pr_upstream: None,
},
));
}
// Prefixed branch exists but tracks something else - error
return Err(GitError::BranchTracksDifferentRef {
branch: prefixed,
ref_type,
number,
}
.into());
}
// This path has no fork push URL, so the branch remains fetch-only.
let remote = remote_ref::find_remote(repo, info)?;
return Ok((
Selector::rewritten_to(prefixed),
CreationMethod::ForkRef {
ref_type,
number,
ref_path: remote_ref::ref_path(forge, number),
fork_push_url: None,
remote,
},
));
}
// The fork URL was missing or did not identify a usable prefix.
return Err(GitError::BranchTracksDifferentRef {
branch: local_branch,
ref_type,
number,
}
.into());
}
// Branch doesn't exist - need to create it with push support.
// Resolve remote and URLs based on platform.
let (fork_push_url, remote) = match ref_type {
RefType::Pr => {
// PR backends include fork URLs in the initial response.
let remote = remote_ref::find_remote(repo, info)?;
(info.fork_push_url.clone(), remote)
}
RefType::Mr => {
// GitLab: fetch project URLs now (deferred from fetch_mr_info for perf)
let urls =
worktrunk::git::remote_ref::gitlab::fetch_gitlab_project_urls(info, repo_root)?;
let target_url = urls.target_url.ok_or_else(|| {
anyhow::anyhow!(
"{} is from a fork but glab didn't provide target project URL; \
upgrade glab or checkout the fork branch manually",
ref_type.display(number)
)
})?;
// find_remote_by_url matches by (host, owner, repo); ssh vs https
// doesn't matter (test_find_remote_by_url_cross_protocol).
let remote = repo.find_remote_by_url(&target_url).ok_or_else(|| {
anyhow::anyhow!(
"No remote found for target project; \
add a remote pointing to {} (e.g., `git remote add upstream {}`)",
target_url,
target_url
)
})?;
if urls.fork_push_url.is_none() {
anyhow::bail!(
"{} is from a fork but glab didn't provide source project URL; \
upgrade glab or checkout the fork branch manually",
ref_type.display(number)
);
}
(urls.fork_push_url, remote)
}
};
Ok((
Selector::rewritten_to(local_branch),
CreationMethod::ForkRef {
ref_type,
number,
ref_path: remote_ref::ref_path(forge, number),
fork_push_url,
remote,
},
))
}
/// Fetch a same-repo PR/MR's source branch with an explicit refspec so the
/// remote-tracking ref exists locally even in repos with limited fetch
/// refspecs (single-branch clones, bare repos).
fn fetch_same_repo_branch(repo: &Repository, info: &RemoteRefInfo) -> anyhow::Result<()> {
let remote = remote_ref::find_remote(repo, info)?;
let branch = &info.source_branch;
eprintln!(
"{}",
progress_message(cformat!("Fetching <bold>{branch}</> from {remote}..."))
);
let refspec = format!("+refs/heads/{branch}:refs/remotes/{remote}/{branch}");
// Use -- to prevent branch names starting with - from being interpreted as flags
repo.run_command(&["fetch", "--", &remote, &refspec])
.with_context(|| cformat!("Failed to fetch branch <bold>{}</> from {}", branch, remote))?;
Ok(())
}
/// Parse a `pr:N` / `mr:N` shortcut into its ref type and number, first
/// normalising a forge PR/MR web URL (e.g.
/// `https://github.com/owner/repo/pull/123`) into the same literal shortcut so
/// both forms flow through one dispatch. Returns `None` for a regular branch
/// name, which callers resolve as an ordinary ref.
fn parse_ref_shortcut(input: &str) -> Option<(RefType, u32)> {
let normalised = parse_ref_url(input);
let input = normalised.as_deref().unwrap_or(input);
if let Some(number) = input
.strip_prefix("pr:")
.and_then(|s| s.parse::<u32>().ok())
{
return Some((RefType::Pr, number));
}
if let Some(number) = input
.strip_prefix("mr:")
.and_then(|s| s.parse::<u32>().ok())
{
return Some((RefType::Mr, number));
}
None
}
/// Resolve a `--base` value, expanding `pr:`/`mr:` shortcuts. Non-shortcut
/// inputs go through [`Repository::expand_selector`] (handles `@`/`-`/`^`).
///
/// Returns the resolved ref plus, when the user picked a `pr:`/`mr:` shortcut
/// against a same-repo PR/MR, the `(remote, branch)` pair the new branch
/// should be configured to track — see [`CreationMethod::Regular`].
///
/// When the bare name doesn't exist locally but a single remote has it,
/// returns the remote-qualified form so the validation in
/// [`creation_method`] doesn't reject `wt switch -c new --base
/// remote-only-branch`. Git's rev-parse doesn't auto-expand `foo` to
/// `refs/remotes/origin/foo`. `git worktree add` does DWIM the bare form, but
/// destructively: given `-b <name>` it drops the `-b` and creates the remote
/// branch's own name instead. So qualifying here is what keeps `--create new-wt
/// --base remote-only-branch` on `new-wt`, which
/// `test_switch_create_with_remote_only_base` pins.
fn resolve_base_ref(
repo: &Repository,
base: &str,
) -> anyhow::Result<(String, Option<(String, String)>)> {
if let Some((ref_type, number)) = parse_ref_shortcut(base) {
let forge = match ref_type {
RefType::Pr => choose_pr_forge(repo)?,
RefType::Mr => ForgeKind::GitLab,
};
return resolve_remote_ref_as_base(repo, forge, number);
}
let selector = repo.expand_selector(base)?;
let resolved = selector.token().to_string();
if !repo.ref_exists(&resolved)? {
let remotes = repo.branch(&resolved).remotes()?;
if remotes.len() == 1 {
return Ok((format!("{}/{}", remotes[0], resolved), None));
}
// Neither a ref nor a branch on a remote: the base may be named by the
// path of the worktree it is checked out in, as targets elsewhere are.
if selector.names_a_path()
&& let Some((_, Some(branch))) = repo.worktree_at_input_path(selector.token())?
{
return Ok((branch, None));
}
}
Ok((resolved, None))
}
/// Resolve `pr:{N}` / `mr:{N}` for `--base`. Same-repo returns the source
/// branch — under its own name, or `<remote>/<branch>` when no local branch
/// has that name — plus the (remote, branch) the new branch should track; fork
/// returns the PR head SHA so we don't create a tracking branch for a ref the
/// user hasn't asked to check out.
fn resolve_remote_ref_as_base(
repo: &Repository,
forge: ForgeKind,
number: u32,
) -> anyhow::Result<(String, Option<(String, String)>)> {
let ref_type = forge.ref_type();
let symbol = ref_type.symbol();
eprintln!(
"{}",
progress_message(cformat!(
"Fetching base {} {symbol}{number}...",
ref_type.name()
))
);
let info = fetch_ref_info(forge, number, repo)?;
eprintln!("{}", format_with_gutter(&format_ref_context(&info), None));
if !info.is_cross_repo {
fetch_same_repo_branch(repo, &info)?;
let remote = remote_ref::find_remote(repo, &info)?;
let branch = &info.source_branch;
// The fetch above writes only `refs/remotes/<remote>/<branch>`, so a
// source branch nobody has checked out locally resolves only under its
// remote: git's rev-parse never expands a bare name to a
// remote-tracking ref, and the bare name would fail the base
// validation in `creation_method`. Same rule, same spelling as
// the remote-only base above.
let base = if repo.ref_exists(branch)? {
branch.clone()
} else {
format!("{remote}/{branch}")
};
return Ok((base, Some((remote, branch.clone()))));
}
let remote = remote_ref::find_remote(repo, &info)?;
let display = ref_type.display(number);
repo.run_command(&[
"fetch",
"--",
&remote,
&remote_ref::tracking_ref(forge, number),
])
.with_context(|| cformat!("Failed to fetch <bold>{display}</> from {remote}"))?;
let sha = repo
.run_command(&["rev-parse", "FETCH_HEAD"])
.context("Failed to resolve FETCH_HEAD to a commit SHA")?
.trim()
.to_string();
Ok((sha, None))
}
/// Resolve a `pr:N` / `mr:N` argument through the forge.
///
/// Returns `None` for any other argument — this is the one form whose branch
/// name can't be derived locally, and the one resolution that costs a forge
/// round-trip. Like every other argument it resolves ahead of the
/// `pre-switch` hooks (#3934), and the forge is queried exactly once.
fn resolve_ref_shortcut_target(
repo: &Repository,
branch: &str,
create: bool,
base: Option<&str>,
) -> anyhow::Result<Option<ResolvedTarget>> {
// `pr:N` dispatches to GitHub, Gitea, or Azure DevOps based on remotes;
// `mr:N` to GitLab. Forge PR/MR web URLs normalise to the same shortcuts.
let Some((ref_type, number)) = parse_ref_shortcut(branch) else {
return Ok(None);
};
// Fail closed on a malformed project config before choosing a forge:
// `forge.platform` lives there, and `configured_forge_platform` reports a
// config that won't parse as "unset", which would route an intended
// override to the wrong CLI. The hook-approval gate used to be what
// surfaced this, but that no longer runs first.
repo.project_config()?;
// --base is invalid with pr:/mr: syntax (check before forge selection,
// which may invoke a forge CLI to inspect authentication).
if base.is_some() {
return Err(GitError::RefBaseConflict { ref_type, number }.into());
}
let forge = match ref_type {
RefType::Pr => choose_pr_forge(repo)?,
RefType::Mr => ForgeKind::GitLab,
};
resolve_remote_ref(repo, forge, number, create).map(Some)
}
/// Decide how a new worktree for `branch` gets created, validating
/// `--create` and `--base`.
///
/// Runs after the `pre-switch` hooks, which may fetch the ref `--base` names
/// or the remote branch `--create` warns about shadowing.
fn creation_method(
repo: &Repository,
branch: &str,
create: bool,
base: Option<&str>,
) -> anyhow::Result<CreationMethod> {
// Resolve and validate base (only used with --create)
let (resolved_base, base_pr_upstream) = match base {
Some(base_str) if create => {
let (resolved, upstream) = resolve_base_ref(repo, base_str)?;
if !repo.ref_exists(&resolved)? {
return Err(GitError::ReferenceNotFound {
reference: resolved,
flag: Some("--base"),
}
.into());
}
(Some(resolved), upstream)
}
_ => (None, None),
};
// Validate --create constraints
if create {
let branch_handle = repo.branch(branch);
branch_handle.require_valid_name()?;
if branch_handle.exists_locally()? {
return Err(GitError::BranchAlreadyExists {
branch: branch.to_string(),
}
.into());
}
// Warn if --create would shadow a remote branch
let remotes = branch_handle.remotes()?;
if !remotes.is_empty() {
let remote_ref = format!("{}/{}", remotes[0], branch);
eprintln!(
"{}",
warning_message(cformat!(
"Branch <bold>{branch}</> exists on remote ({remote_ref}); creating new branch from base instead"
))
);
// `--foreground` is required: background removal leaves a placeholder
// directory at the original path (to keep shell PWD valid), which
// would block the subsequent `wt switch` with "Directory already exists".
let remove_cmd = suggest_command("remove", &[branch], &["--foreground"]);
let switch_cmd = suggest_command("switch", &[branch], &[]);
eprintln!(
"{}",
hint_message(cformat!(
"To switch to the remote branch, delete this branch and run without <underline>--create</>: <underline>{remove_cmd} && {switch_cmd}</>"
))
);
}
}
// Compute base branch for creation. The default branch is a base like any
// `--base` value, so any ref that resolves to a commit qualifies — a
// remote-tracking default such as git-p4's `p4/master` has no local
// branch (#4481). When the cached default no longer resolves, return None
// and create from HEAD.
let base_branch = if create {
match resolved_base {
Some(base) => Some(base),
None => match repo.resolve_target_branch(None) {
Ok(base) if repo.ref_exists(&base)? => Some(base),
_ => None,
},
}
} else {
None
};
Ok(CreationMethod::Regular {
create_branch: create,
base_branch,
base_pr_upstream,
})
}
/// Validate that we can create a worktree at the given path.
///
/// Checks:
/// - Path not occupied by another worktree
/// - For regular switches (not --create), branch must exist
/// - Handles --clobber for stale directories
///
/// Note: Fork PR/MR branch existence is checked earlier in resolve_fork_ref()
/// where we can also check if it's tracking the correct PR/MR.
fn validate_worktree_creation(
repo: &Repository,
branch: &str,
path: &Path,
clobber: bool,
method: &CreationMethod,
from_path_flag: bool,
) -> anyhow::Result<bool> {
// For regular switches without --create, validate branch exists
if let CreationMethod::Regular {
create_branch: false,
..
} = method
&& !repo.branch(branch).exists()?
{
if !worktrunk::git::is_valid_branch_name(branch) {
return Err(GitError::WorktreeSelectorNotFound {
selector: branch.to_string(),
}
.into());
}
return Err(GitError::BranchNotFound {
branch: branch.to_string(),
show_create_hint: true,
last_fetch_ago: format_last_fetch_ago(repo),
pr_mr_platform: repo.detect_ref_type(),
}
.into());
}
// Check if path is occupied by another worktree
if let Some((existing_path, occupant)) = repo.worktree_at_path(path)? {
if !existing_path.exists() {
let occupant_branch = occupant.unwrap_or_else(|| branch.to_string());
return Err(GitError::worktree_missing(occupant_branch, &existing_path).into());
}
return Err(GitError::WorktreePathOccupied {
branch: branch.to_string(),
path: path.to_path_buf(),
occupant,
}
.into());
}
// Handle clobber for stale directories. Returns whether `execute_switch`
// must back up a path occupying `worktree_path` before creating the
// worktree; the backup itself happens at execution time so a path that
// races in after planning is still moved atomically (see
// `back_up_clobbered_path`).
if !path.exists() {
return Ok(false);
}
if clobber {
return Ok(true);
}
let is_create = matches!(
method,
CreationMethod::Regular {
create_branch: true,
..
}
);
Err(GitError::WorktreePathExists {
branch: branch.to_string(),
path: path.to_path_buf(),
create: is_create,
from_path_flag,
}
.into())
}
/// Set up a local branch and its worktree for a fork PR or MR.
///
/// One `git worktree add -b <branch> -- <path> FETCH_HEAD` creates the branch
/// and the worktree together, exactly as the [`CreationMethod::Regular`] arm
/// does. Git rejects a name that is already taken before writing anything, so
/// the one failure that lands on a branch this function did not create leaves
/// it untouched, and no caller needs a rollback. (Git is not atomic in
/// general: a destination path occupied between planning and here leaves the
/// new branch behind — the leftover the `Regular` arm already accepts, a stray
/// branch at the PR head rather than someone's work. It carries the same
/// follow-on cost as a failed tracking write, below: no config was written, so
/// the next `wt switch pr:N` takes the prefixed-branch path or errors. The old
/// code did roll this one case back cleanly, its own branch being the only
/// thing it could have deleted — but distinguishing it needs the very
/// did-we-create-it reasoning that produced the bug.)
///
/// The creating call comes first so nothing is written until the name is won.
/// Configuring tracking (`remote`, `merge`, `pushRemote`) ahead of it would
/// rewrite the *existing* branch's upstream on exactly the collision above —
/// the same class of bug as the rollback this replaced.
///
/// A tracking write that fails afterwards leaves a branch and worktree at the
/// PR/MR head with incomplete config. Nothing is lost and a re-run is
/// non-destructive, but it isn't a no-op either: `branch_tracks_ref` reads that
/// branch as tracking something else, so the next `wt switch pr:N` takes the
/// prefixed-branch path (GitHub/Gitea) or reports `BranchTracksDifferentRef`
/// (GitLab/Azure DevOps). Only a failed `pushRemote` write — the last one, with
/// the other two landed — leaves a branch the next run adopts directly.
///
/// The caller records the created worktree before configuring tracking, so
/// a tracking error preserves that result.
fn create_fork_worktree(
repo: &Repository,
branch: &str,
worktree_path: &Path,
) -> anyhow::Result<()> {
// Create branch and worktree in one command (delayed streaming: silent if
// fast, shows progress if slow). `-b <branch>` keeps the branch name as the
// value of a flag, and `--` separates the path and start point, so neither
// can be read as an option when it begins with `-`.
//
// No `-c branch.autoSetupMerge=…` here, unlike the `Regular` arm: git sets
// up tracking only where the start point resolves under `refs/heads/` or
// `refs/remotes/`, and `FETCH_HEAD` resolves as itself. Under every value
// of the setting — `always` included — git writes no tracking config from
// this start point, leaving `configure_fork_branch` as the only writer.
let worktree_path_str = worktree_path.to_string_lossy();
let git_args = [
"worktree",
"add",
"-b",
branch,
"--",
worktree_path_str.as_ref(),
"FETCH_HEAD",
];
repo.run_command_delayed_stream(
&git_args,
Repository::SLOW_OPERATION_DELAY_MS,
Some(
progress_message(cformat!("Creating worktree for <bold>{}</>...", branch)).to_string(),
),
)
.map_err(|e| {
// No leftover-branch hint here: `wt switch pr:N` adopts or prefixes
// the branch on re-run, so naming the ref would suggest the wrong recovery.
worktree_creation_error(repo, e, branch.to_string(), None, false)
})?;
Ok(())
}
fn configure_fork_branch(
repo: &Repository,
branch: &str,
remote: &str,
remote_ref: &str,
fork_push_url: Option<&str>,
) -> anyhow::Result<()> {
// Configure branch tracking for pull and push
let branch_remote_key = format!("branch.{}.remote", branch);
let branch_merge_key = format!("branch.{}.merge", branch);
let merge_ref = format!("refs/{}", remote_ref);
repo.set_config(&branch_remote_key, remote)
.with_context(|| format!("Failed to configure branch.{}.remote", branch))?;
repo.set_config(&branch_merge_key, &merge_ref)
.with_context(|| format!("Failed to configure branch.{}.merge", branch))?;
// Only configure pushRemote if we have a fork URL (not using prefixed branch)
if let Some(url) = fork_push_url {
let branch_push_remote_key = format!("branch.{}.pushRemote", branch);
repo.set_config(&branch_push_remote_key, url)
.with_context(|| format!("Failed to configure branch.{}.pushRemote", branch))?;
}
Ok(())
}
/// Validate and plan a switch operation.
///
/// This performs all validation upfront, returning a `SwitchPlan` that can be
/// executed later. Call this BEFORE approval prompts to ensure users aren't
/// asked to approve hooks for operations that will fail.
///
/// Warnings (remote branch shadow, --base without --create, invalid default branch)
/// are printed during planning since they're informational, not blocking.
fn plan_switch(
repo: &Repository,
target: SwitchTarget,
create: bool,
base: Option<&str>,
path: Option<&Path>,
clobber: bool,
config: &UserConfig,
) -> anyhow::Result<SwitchPlan> {
// Record the worktree being left, for `wt switch -`
let current = repo.current_worktree();
let new_previous = current.root().ok().zip(current.branch().ok());
if base.is_some() && !create {
eprintln!(
"{}",
warning_message("--base flag is only used with --create, ignoring")
);
}
// Resolve `--path` the way git resolves `git worktree add <path>`: from
// the directory wt was pointed at, normalized so the comparisons below and
// the path git records agree.
let requested_path = path
.map(|path| -> anyhow::Result<PathBuf> {
Ok(std::path::absolute(resolve_input_path(path))?.normalize())
})
.transpose()?;
let SwitchTarget {
destination,
remote_ref,
} = target;
// Phase 1: an existing worktree answers without the ~7 git commands
// `compute_worktree_path` runs.
let branch = match destination {
SwitchDestination::Existing { path, branch } => {
let name = branch
.clone()
.unwrap_or_else(|| worktrunk::git::path_dir_name(&path).to_string());
// A registration whose directory is gone or broken has nothing to
// switch into; `wt remove` is the one command that still wants it.
if repo.worktree_is_unusable(&path)? {
return Err(GitError::worktree_missing(name, &path).into());
}
// `--path` only places a new worktree. Naming a different
// directory for one that already exists would otherwise be
// silently ignored.
if let Some(requested) = requested_path.as_deref()
&& !same_worktree_path(requested, &path)
{
let existing = format_path_for_display(&path);
let requested = format_path_for_display(requested);
bail!(cformat!(
"<bold>{name}</> already has a worktree @ <bold>{existing}</>, not <bold>{requested}</>; to switch to it, run without <bold>--path</>"
));
}
return Ok(SwitchPlan::Existing {
path: operational_worktree_path(path),
branch,
new_previous,
});
}
SwitchDestination::New { branch } => branch,
};
// Phase 2: how to create it (validates --create/--base; `pr:`/`mr:`
// arrived with the forge's answer)
let (method, ref_identity) = match remote_ref {
Some(target) => (target.method, Some(target.ref_identity)),
None => (creation_method(repo, &branch, create, base)?, None),
};
// Phase 3: Compute expected path. `--path` replaces the template outright.
let from_path_flag = requested_path.is_some();
let expected_path = match requested_path {
Some(path) => {
reject_path_overlapping_worktrees(repo, &path)?;
path
}
None => compute_worktree_path(repo, &branch, config)?,
};
// Phase 4: Validate we can create at this path
let needs_clobber_backup = validate_worktree_creation(
repo,
&branch,
&expected_path,
clobber,
&method,
from_path_flag,
)?;
// Phase 5: Return the plan
Ok(SwitchPlan::Create {
branch,
worktree_path: expected_path,
method,
ref_identity,
needs_clobber_backup,
new_previous,
})
}
/// Refuse a `--path` directory that holds a worktree or the repository, that
/// sits inside one, or that is its git directory.
///
/// Such a directory always exists, so `validate_worktree_creation` would
/// otherwise offer `--clobber`, which moves it aside: `--path ..` would move
/// the repository itself, and `--path src` a tracked directory of the current
/// worktree. The template never produces these; a typed path easily does. A
/// directory that does not exist yet is left alone — nesting a new worktree
/// inside another is git's call, not a clobber.
fn reject_path_overlapping_worktrees(repo: &Repository, requested: &Path) -> anyhow::Result<()> {
if !requested.exists() {
return Ok(());
}
// The comparison form: `dunce` keeps `\\?\` on a deep Windows path and
// drops it from a short root, which `starts_with` reads as unrelated.
let requested = canonicalize_with_parents(requested);
let registered = repo
.list_worktrees()?
.iter()
.map(|wt| (wt.path.as_path(), true));
for (existing, is_worktree) in registered.chain([(repo.git_common_dir(), false)]) {
let existing = canonicalize_with_parents(existing);
if existing == requested {
// A worktree at exactly this path is `validate_worktree_creation`'s
// to report, naming its branch. The git directory has no such
// check; in a bare repository it is the repository itself.
if is_worktree {
continue;
}
let requested = format_path_for_display(&requested);
bail!(cformat!(
"<bold>--path {requested}</> is the repository's git directory; choose a directory outside the repository and its worktrees"
));
}
let relation = if existing.starts_with(&requested) {
"contains"
} else if requested.starts_with(&existing) {
"is inside"
} else {
continue;
};
let requested = format_path_for_display(&requested);
let existing = format_path_for_display(&existing);
bail!(cformat!(
"<bold>--path {requested}</> {relation} <bold>{existing}</>; choose a directory outside the repository and its worktrees"
));
}
Ok(())
}
/// Preserve the filesystem spelling Git and downstream commands can operate
/// on. This is deliberately separate from [`WorktreeId`]'s comparison form:
/// on deep Windows paths, `dunce` keeps the `\\?\` prefix while the identity
/// drops it so paths on opposite sides of the legacy-length threshold compare.
fn operational_worktree_path(path: PathBuf) -> PathBuf {
canonicalize(&path).unwrap_or(path)
}
fn same_worktree_path(left: &Path, right: &Path) -> bool {
WorktreeId::new(left) == WorktreeId::new(right)
}
/// Execute a validated switch plan.
///
/// Takes a `SwitchPlan` from `plan_switch()` and executes it.
/// For `SwitchPlan::Existing`, just records history.
/// For `SwitchPlan::Create`, creates the worktree and runs hooks.
fn execute_switch(
repo: &Repository,
plan: SwitchPlan,
config: &UserConfig,
force: bool,
run_hooks: bool,
hook_plan: &ApprovedHookPlan,
) -> CommandResult<(SwitchResult, SwitchBranchInfo)> {
match plan {
SwitchPlan::Existing {
path,
branch,
new_previous,
} => {
let already_at_worktree = std::env::current_dir()
.ok()
.is_some_and(|current| same_worktree_path(¤t, &path));
// Only update switch history when actually switching worktrees.
// Updating on AlreadyAt would corrupt `wt switch -` by recording
// the current branch as "previous" even though no switch occurred.
if !already_at_worktree && let Some((path, branch)) = &new_previous {
let _ = repo.record_switch_source(path, branch.as_deref());
}
let result = if already_at_worktree {
SwitchResult::AlreadyAt(path)
} else {
SwitchResult::Existing { path }
};
Ok((result, SwitchBranchInfo { branch }))
}
SwitchPlan::Create {
branch,
worktree_path,
method,
ref_identity,
needs_clobber_backup,
new_previous,
} => {
// Handle --clobber backup if needed (shared for all creation methods)
if needs_clobber_backup {
// Atomically move the stale path aside, to a timestamped backup
// name. A name already taken (a same-second clobber, or one
// that raced in after planning) is never overwritten — the move
// falls back to the next free `-N` name.
let backup_path = back_up_clobbered_path_now(&worktree_path)?;
let path_display = worktrunk::path::format_path_for_display(&worktree_path);
let backup_display = worktrunk::path::format_path_for_display(&backup_path);
eprintln!(
"{}",
warning_message(cformat!(
"Moved <bold>{path_display}</> to <bold>{backup_display}</> (--clobber)"
))
);
}
// Execute based on creation method
let (created_branch, base_branch, from_remote, detect_tracking) = match &method {
CreationMethod::Regular {
create_branch,
base_branch,
..
} => {
// Check if local branch exists BEFORE git worktree add (for DWIM detection)
let branch_handle = repo.branch(&branch);
let local_branch_existed = !create_branch && branch_handle.exists_locally()?;
// Build git worktree add command. Options come first, then
// `--` separates them from the path and any positional ref,
// so branch/base names that begin with `-` cannot be
// misinterpreted by git as flags. `-b <branch>` keeps the
// branch as the *value* of `-b`, which is safe even when
// the branch name starts with `-`.
let worktree_path_str = worktree_path.to_string_lossy();
let mut args: Vec<&str> = Vec::new();
// Safety: `wt` decides tracking for a branch it creates,
// rather than the user's `branch.autoSetupMerge`. `-c`
// outranks every config file, so the outcome is the same on
// every machine. Git's `simple` is the rule `wt` wants: an
// upstream only when the new branch's name matches the remote
// branch it starts from, which is exactly when inherited
// tracking is right. Git's default `true`, and `always`, would
// have `--create feature --base origin/release` track
// `origin/release`, so a bare `git push` under
// `push.default = upstream` pushes the new work to `release`
// (#713); `false` and `inherit` would deny the tracking that is
// the point of a same-named branch — `--create release --base
// origin/release`, and every DWIM `wt switch feature` from
// `origin/feature`, which is the tracking branch the docs
// promise. Both paths run under the one rule, so `wt switch`
// has one answer to state.
//
// `wt` sets git's rule rather than picking `--track` /
// `--no-track` from a name comparison of its own, because only
// git maps the base back to a remote branch through the fetch
// refspec. Splitting `<remote>/<branch>` reads
// `team/fork/release` as branch `fork/release`, so the verdict
// inverts both ways, and a refspec that renames into a
// sub-namespace does the same. `--track` is also a hard demand
// where `simple` is best-effort: it fails the whole command
// when the base isn't refspec-mapped, as in a single-branch
// clone holding a hand-fetched ref.
args.extend(["-c", "branch.autoSetupMerge=simple"]);
args.extend(["worktree", "add"]);
// For DWIM fallback: when the branch doesn't exist locally,
// git worktree add relies on DWIM to auto-create it from a
// remote tracking branch. DWIM fails in repos without configured
// fetch refspecs (bare repos, single-branch clones). Explicitly
// create from the tracking ref in that case.
let tracking_ref;
let trailing_ref: Option<&str> = if *create_branch {
args.push("-b");
args.push(&branch);
base_branch.as_deref()
} else if !local_branch_existed {
// Explicit -b when there's exactly one remote tracking ref.
// Git's DWIM relies on the fetch refspec including this branch,
// which may not hold in single-branch clones or bare repos.
let remotes = branch_handle.remotes().unwrap_or_default();
if remotes.len() == 1 {
tracking_ref = format!("{}/{}", remotes[0], branch);
args.extend(["-b", &branch]);
Some(tracking_ref.as_str())
} else {
// Multiple or zero remotes: let git's DWIM handle (or error)
Some(branch.as_str())
}
} else {
Some(branch.as_str())
};
args.push("--");
args.push(worktree_path_str.as_ref());
if let Some(r) = trailing_ref {
args.push(r);
}
// Delayed streaming: silent if fast, shows progress if slow
let progress_msg = Some(
progress_message(cformat!("Creating worktree for <bold>{}</>...", branch))
.to_string(),
);
if let Err(e) = repo.run_command_delayed_stream(
&args,
Repository::SLOW_OPERATION_DELAY_MS,
progress_msg,
) {
return Err(worktree_creation_error(
repo,
e,
branch.clone(),
base_branch.clone(),
*create_branch,
)
.into());
}
if *create_branch {
// A new branch starts without the marker of an earlier
// branch that had the same name and was deleted
// outside `wt`.
repo.clear_branch_marker(&branch);
}
(
*create_branch,
base_branch.clone(),
None,
!create_branch && !local_branch_existed,
)
}
CreationMethod::ForkRef {
ref_type,
number,
ref_path,
remote,
..
} => {
let label = ref_type.display(*number);
// Fetch the ref (remote was resolved during planning)
// Use -- to prevent refs starting with - from being interpreted as flags
repo.run_command(&["fetch", "--", remote, ref_path])
.with_context(|| format!("Failed to fetch {} from {}", label, remote))?;
// No rollback on failure. One here used to delete the
// branch on any error, so the "a branch named 'X' already
// exists" case force-deleted a branch `wt` had not created,
// taking any commits only it held. `create_fork_worktree`
// leaves nothing for a rollback to clean up.
create_fork_worktree(repo, &branch, &worktree_path)?;
(false, None, Some(label), false)
}
};
// Compute base worktree path for hooks and result.
//
// `git worktree add` already mutated the worktree list, but `repo`
// cached it pre-start (populated by `plan_switch`). Reading
// `worktree_for_branch` through `repo` here would observe the stale
// pre-start inventory — see the caching contract in
// `git/repository/mod.rs`. Probe through a fresh `Repository::at`
// so the lookup reflects the post-start state.
let base_worktree_path = base_branch
.as_ref()
.and_then(|b| {
Repository::at(repo.discovery_path())
.and_then(|fresh| fresh.worktree_for_branch(b))
.ok()
.flatten()
})
.map(|p| worktrunk::path::to_posix_path(&p.to_string_lossy()));
// PR/MR identity for the pre-start hook below. It rides the plan,
// not `method`: a same-repo PR resolves to
// `CreationMethod::Regular`, and reading `method` left the common
// case with no `pr_number`. The post-* hooks get the same value
// from the pipeline's own copy rather than back off the
// `SwitchResult`, which would leave the `Existing` path unserved.
let (pr_number, pr_url) = match &ref_identity {
Some(RefIdentity { number, url }) => (Some(*number), Some(url.clone())),
None => (None, None),
};
let mut result = SwitchResult::Created {
path: worktree_path.clone(),
created_branch,
base_branch,
base_worktree_path: base_worktree_path.clone(),
from_remote,
};
// Creation is committed. Keep the typed outcome through tracking
// setup and hooks, which can still fail independently.
let finish = (|| -> anyhow::Result<()> {
match &method {
CreationMethod::Regular {
create_branch,
base_pr_upstream,
..
} => {
// A same-repo PR/MR base tracks its source branch even
// when the user chose a different local branch name.
if *create_branch
&& let Some((upstream_remote, upstream_branch)) = base_pr_upstream
{
repo.set_config(&format!("branch.{branch}.remote"), upstream_remote)?;
repo.set_config(
&format!("branch.{branch}.merge"),
&format!("refs/heads/{upstream_branch}"),
)?;
}
if detect_tracking
&& let SwitchResult::Created { from_remote, .. } = &mut result
{
*from_remote = repo.branch(&branch).upstream()?;
}
}
CreationMethod::ForkRef {
ref_path,
fork_push_url,
remote,
..
} => {
configure_fork_branch(
repo,
&branch,
remote,
ref_path,
fork_push_url.as_deref(),
)?;
if let Some(url) = fork_push_url {
eprintln!(
"{}",
info_message(cformat!(
"Push configured to fork: <underline>{url}</>"
))
);
} else {
eprintln!(
"{}",
warning_message(cformat!(
"Using prefixed branch name <bold>{branch}</> due to name conflict"
))
);
eprintln!(
"{}",
hint_message(
"Push to fork is not supported with prefixed branches; feedback welcome at https://github.com/max-sixty/worktrunk/issues/714"
)
);
}
}
}
// Execute pre-start commands. `hook_repo` roots the render context
// in the new worktree (created just above); the commands come from
// the frozen `hook_plan`, selected at the gate from the invoking
// worktree's config.
if run_hooks {
let hook_repo = Repository::at(&worktree_path)?;
let ctx = CommandContext::new(
&hook_repo,
config,
Some(&branch),
&worktree_path,
force,
);
let mut vars = TemplateVars::new()
.with_target(&branch)
.with_target_worktree_path(&worktree_path)
.with_pr(pr_number, pr_url.as_deref());
if let CreationMethod::Regular { base_branch, .. } = &method {
vars = vars
.with_base_strs(base_branch.as_deref(), base_worktree_path.as_deref());
}
ctx.execute_pre_create_commands(
&vars.as_extra_vars(),
hook_plan,
&worktree_path,
)?;
}
// Record successful switch in history
if let Some((path, branch)) = &new_previous {
let _ = repo.record_switch_source(path, branch.as_deref());
}
Ok(())
})();
let outcome = (
result,
SwitchBranchInfo {
branch: Some(branch),
},
);
match finish {
Ok(()) => Ok(outcome),
Err(error) => Err(CommandFailure::with_result(error, outcome)),
}
}
}
}
/// Detect a git ref directory/file (D/F) conflict for a branch about to be
/// created, returning an existing branch it collides with.
///
/// Git stores refs as file paths under `refs/heads/`, so a branch name can't
/// be both a file and a directory: creating `release` fails when
/// `release/2026.4` exists, and creating `release/foo` fails when `release`
/// exists. This inspects the cached local-branch inventory (no extra
/// subprocess) for either shape and returns the first colliding branch.
fn detect_branch_namespace_conflict(repo: &Repository, branch: &str) -> Option<String> {
let prefix = format!("{branch}/");
repo.local_branches()
.ok()?
.iter()
.map(|b| b.name.as_str())
.find(|name| {
// `branch` is a directory prefix of an existing branch, or an
// existing branch is a directory prefix of `branch`.
name.starts_with(&prefix) || branch.starts_with(&format!("{name}/"))
})
.map(String::from)
}
/// Classify a failed `git worktree add` before inspecting any further Git state.
/// Interruptions retain their native error beneath a single-line context.
/// Ordinary failures identify namespace conflicts or render the command output.
///
/// Regular branch creation inspects whether the failed add left its `-b` branch
/// behind, adding a recovery hint. Fork creation has its own re-run recovery.
fn worktree_creation_error(
repo: &Repository,
err: anyhow::Error,
branch: String,
base_branch: Option<String>,
inspect_leftover: bool,
) -> anyhow::Error {
if err.interrupt_signal().is_some() {
return err.context("Worktree creation interrupted");
}
// Git stores refs as paths, so `release` and `release/2026.4` cannot coexist.
if let Some(conflicting) = detect_branch_namespace_conflict(repo, &branch) {
return GitError::BranchNamespaceConflict {
branch,
conflicting,
}
.into();
}
let leftover_branch = inspect_leftover && failed_add_left_branch(repo, &branch);
let (output, command) = Repository::extract_failed_command(&err);
GitError::WorktreeCreationFailed {
branch,
base_branch,
error: output,
command,
leftover_branch,
}
.into()
}
/// Whether a failed `git worktree add -b <branch>` left the branch behind.
///
/// Git writes the ref before it populates the worktree and unwinds only what it
/// registered, so a failure in between — an index it can't write, a path whose
/// leading directories it can't create — ends with the branch present and
/// nothing checked out on it. The next `wt switch --create <branch>` then
/// reports `Branch … already exists`, which reads as a fresh name collision
/// rather than as fallout from the first failure (issue #4108).
///
/// Read-only on purpose: `wt` names the leftover, it never deletes it. A branch
/// is the user's, and the rollback this would otherwise be is the one #3984
/// removed — its did-we-create-it reasoning force-deleted a branch `wt` had not
/// created. A hint costs nothing and leaves the choice where it belongs.
///
/// Only the `--create` path asks. Without `--create` the leftover branch is
/// what a re-run wants anyway, so there is nothing to explain.
///
/// The worktree lookup goes through a fresh [`Repository`]: the failed add may
/// still have registered one, and `repo` cached its inventory before the
/// command ran (see the caching contract in `git/repository/mod.rs`).
fn failed_add_left_branch(repo: &Repository, branch: &str) -> bool {
repo.branch(branch).exists_locally().unwrap_or(false)
&& Repository::at(repo.discovery_path())
.and_then(|fresh| fresh.worktree_for_branch(branch))
.is_ok_and(|worktree| worktree.is_none())
}
/// Format the last fetch time as a self-contained phrase for error hint parentheticals.
///
/// Returns e.g. "last fetched 3h ago" or "last fetched just now".
/// Returns `None` if FETCH_HEAD doesn't exist (never fetched).
fn format_last_fetch_ago(repo: &Repository) -> Option<String> {
let epoch = repo.last_fetch_epoch()?;
let relative = format_relative_time_short(epoch as i64);
if relative == "now" || relative == "future" {
Some("last fetched just now".to_string())
} else {
Some(format!("last fetched {relative} ago"))
}
}
/// Structured output for `wt switch --format=json`.
#[derive(Serialize)]
struct SwitchJsonOutput {
action: &'static str,
/// Branch name
#[serde(skip_serializing_if = "Option::is_none")]
branch: Option<String>,
/// Absolute worktree path
path: PathBuf,
/// True if branch was created (--create flag)
#[serde(skip_serializing_if = "Option::is_none")]
created_branch: Option<bool>,
/// Base branch when creating (e.g., "main")
#[serde(skip_serializing_if = "Option::is_none")]
base_branch: Option<String>,
/// Remote tracking branch if auto-created
#[serde(skip_serializing_if = "Option::is_none")]
from_remote: Option<String>,
}
impl SwitchJsonOutput {
fn from_result(result: &SwitchResult, branch_info: &SwitchBranchInfo) -> Self {
let (action, path, created_branch, base_branch, from_remote) = match result {
SwitchResult::AlreadyAt(path) => ("already_at", path, None, None, None),
SwitchResult::Existing { path } => ("existing", path, None, None, None),
SwitchResult::Created {
path,
created_branch,
base_branch,
from_remote,
..
} => (
"created",
path,
Some(*created_branch),
base_branch.clone(),
from_remote.clone(),
),
};
Self {
action,
branch: branch_info.branch.clone(),
path: path.clone(),
created_branch,
base_branch,
from_remote,
}
}
}
/// Options for the switch command
struct SwitchOptions<'a> {
branch: &'a str,
create: bool,
base: Option<&'a str>,
path: Option<&'a Path>,
execute: Option<&'a str>,
execute_args: &'a [String],
yes: bool,
clobber: bool,
/// Resolved from --cd/--no-cd flags: Some(true) = cd, Some(false) = no cd, None = use config
change_dir: Option<bool>,
verify: bool,
format: crate::cli::SwitchFormat,
}
/// Run pre-switch hooks before worktree creation, returning whether any ran.
///
/// `target` is the destination as resolved before the hooks, so
/// `{{ branch }}`, `{{ target }}`, and `{{ target_worktree_path }}` describe
/// where the switch lands however the argument named it: a shortcut, `pr:N`,
/// a remote-tracking name, or a worktree's path.
///
/// Directional vars:
/// - `base` / `base_worktree_path`: current (source) branch and worktree
/// - `target` / `target_worktree_path`: destination branch and worktree (if it exists)
/// - `pr_number` / `pr_url`: the PR/MR a `pr:N` / `mr:N` argument named
fn run_pre_switch_hooks(
repo: &Repository,
config: &UserConfig,
target: &SwitchTarget,
yes: bool,
) -> anyhow::Result<bool> {
let current_wt = repo.current_worktree();
let current_path = current_wt.path().to_path_buf();
// A detached destination has no branch, which leaves `branch` and
// `target` unset (issue #4009).
let dest_branch = target.branch();
let dest_path = match &target.destination {
SwitchDestination::Existing { path, .. } => Some(path.as_path()),
SwitchDestination::New { .. } => None,
};
let pre_ctx = CommandContext::new(repo, config, dest_branch, ¤t_path, yes);
if !approve_hooks(&pre_ctx, &[HookType::PreSwitch])? {
return Ok(false);
}
// Base vars: source (where the user currently is). Target vars and
// Active overrides come from the destination worktree if it exists —
// for creates the planned path is computed later during plan_switch,
// so worktree_path stays at its default (the source = cwd).
// A detached source worktree leaves `base` unset rather than empty,
// matching `branch` and what `wt hook pre-switch` already renders
// there (issue #4009).
let base_branch = current_wt.branch().ok().flatten();
let ref_identity = target.ref_identity();
let mut vars = TemplateVars::new()
.with_base(base_branch.as_deref(), ¤t_path)
.with_target_opt(dest_branch)
.with_pr(
ref_identity.map(|id| id.number),
ref_identity.map(|id| id.url.as_str()),
);
if let Some(p) = dest_path {
vars = vars.with_target_worktree_path(p).with_active_worktree(p);
// Without a branch, `commit` would otherwise read HEAD where the
// hook runs — the source worktree.
if dest_branch.is_none()
&& let Ok(Some(commit)) = repo.worktree_at(p).head_sha()
&& let Ok(short) = repo.short_sha(&commit)
{
vars = vars.with_active_commit(&commit, &short);
}
}
let extra_vars = vars.as_extra_vars();
execute_hook(
&pre_ctx,
HookType::PreSwitch,
&extra_vars,
FailureStrategy::FailFast,
)
}
/// Hook types that apply after a switch operation.
///
/// Creates trigger pre-start + post-start + post-switch hooks;
/// existing worktrees trigger only post-switch.
fn switch_post_hook_types(is_create: bool) -> &'static [HookType] {
if is_create {
&[
HookType::PreCreate,
HookType::PostCreate,
HookType::PostSwitch,
]
} else {
&[HookType::PostSwitch]
}
}
/// Approve switch hooks upfront and show "Commands declined" if needed.
///
/// Switch hooks resolve their commands from the invoking worktree's
/// `.config/wt.toml` — the worktree `wt switch` ran in. Selecting them here,
/// at the gate, freezes the exact commands `execute_switch` will run into the
/// [`ApprovedHookPlan`].
///
/// Returns `(hooks_approved, plan)`. `hooks_approved` is `false` and the plan
/// empty when `!verify` or the user declined; the covered switch hooks
/// (`pre-start` / `post-start` / `post-switch`) execute only from `plan`.
fn approve_switch_hooks(
repo: &Repository,
config: &UserConfig,
plan: &SwitchPlan,
yes: bool,
verify: bool,
) -> anyhow::Result<(bool, ApprovedHookPlan)> {
if !verify {
return Ok((false, ApprovedHookPlan::empty()));
}
// Non-fatal: a destination with no project hooks must still switch even
// when the project identifier can't be resolved (the plan ends up empty
// and `approve` never needs it).
let project_id = repo.project_identifier().ok();
let pid = project_id.as_ref();
let project_config = repo.load_project_config()?;
let mut builder = HookPlanBuilder::new(project_config.as_ref(), config, pid);
builder.add(
plan.worktree_path(),
switch_post_hook_types(plan.is_create()),
);
match builder.finish().approve(pid, yes)? {
Some(approved) => Ok((true, approved)),
None => {
let on_decline = if plan.is_create() {
"Commands declined, continuing worktree creation without hooks"
} else {
"Commands declined, switching without hooks"
};
eprintln!("{}", info_message(on_decline));
Ok((false, ApprovedHookPlan::empty()))
}
}
}
/// Spawn post-switch (and post-start for creates) background hooks.
fn spawn_switch_background_hooks(
config: &UserConfig,
result: &SwitchResult,
branch: Option<&str>,
yes: bool,
extra_vars: &[(&str, &str)],
hooks_display_path: Option<&Path>,
hook_plan: &ApprovedHookPlan,
) -> anyhow::Result<()> {
// The common case (no project hooks configured): nothing to render or
// announce, so skip building the destination-rooted `Repository` — it
// would only be discarded by `HookAnnouncer::flush`'s own no-op-when-empty
// check below.
if hook_plan.is_empty() {
return Ok(());
}
// Background hooks run in the new/destination worktree. `hook_repo` roots
// the *render* context there; the command set is the frozen `hook_plan`
// (selected at the gate from the invoking worktree's config), so no
// `.config/wt.toml` is re-read.
let hook_repo = Repository::at(result.path())?;
let ctx = CommandContext::new(&hook_repo, config, branch, result.path(), yes);
let mut announcer = HookAnnouncer::new(&hook_repo, false);
register_planned(
&mut announcer,
hook_plan,
result.path(),
&ctx,
HookType::PostSwitch,
extra_vars,
hooks_display_path,
)?;
if matches!(result, SwitchResult::Created { .. }) {
register_planned(
&mut announcer,
hook_plan,
result.path(),
&ctx,
HookType::PostCreate,
extra_vars,
hooks_display_path,
)?;
}
announcer.flush()
}
/// Capture the source worktree's branch and root for `{{ base }}` /
/// `{{ base_worktree_path }}` in post-switch hooks. Returns empty strings
/// when recovered from a deleted CWD — the source worktree is gone, and
/// `current_worktree()` would resolve to the recovered ancestor (typically
/// the main worktree), which would misleadingly report main's branch/path
/// as the user's "base".
fn capture_switch_source(repo: &Repository, is_recovered: bool) -> (String, String) {
if is_recovered {
return (String::new(), String::new());
}
let source_branch = repo
.current_worktree()
.branch()
.ok()
.flatten()
.unwrap_or_default();
let source_path = repo
.current_worktree()
.root()
.ok()
.map(|p| worktrunk::path::to_posix_path(&p.to_string_lossy()))
.unwrap_or_default();
(source_branch, source_path)
}
/// The full switch sequence shared by the argument path ([`run_switch`]) and
/// the interactive picker.
///
/// Each caller only supplies the identifier and loads config; everything
/// else runs in [`SwitchPipeline::run`] — target resolution, the bare-repo
/// path-fix offer, pre-switch hooks, source-identity capture, `plan_switch` →
/// `approve_switch_hooks` → `validate_switch_templates` → `execute_switch` →
/// output → background hooks → `--execute` → JSON result. One sequence, so the
/// two entry points cannot drift. In particular the single `verify` / `yes` pair gates
/// every hook, so the picker and the argument path cannot diverge on hook
/// approval — the picker once auto-approved `pre-switch` hooks because it kept
/// its own copy of that call.
///
/// The picker-vs-argument differences are field values, not separate code: the
/// picker passes `verify: true`, `yes: false`, `suggestion_ctx: None`, and
/// `shell_integration_binary: None`. It threads `execute` / `execute_args`
/// through from `wt switch -x <cmd>` (no branch), and — like the argument path
/// — captures the pre-switch source worktree, so a picked worktree runs the
/// command and resolves its `{{ base }}` exactly as the argument path does.
/// Source capture is no longer a divergence axis: both entry points always
/// capture, with `is_recovered` the only thing that suppresses it.
pub(crate) struct SwitchPipeline<'a> {
pub repo: &'a Repository,
/// Mutable because the bare-repo path-fix offer
/// (`offer_bare_repo_worktree_path_fix`) and the shell-integration offer
/// (`prompt_shell_integration`) record onto it; every other step reborrows
/// it shared.
pub config: &'a mut UserConfig,
/// Branch identifier — a CLI argument or the picker's selection. Symbolic
/// forms (`-`, `@`, `pr:`/`mr:`) and worktree paths are resolved by
/// [`SwitchTarget::resolve`].
pub identifier: &'a str,
pub create: bool,
pub base: Option<&'a str>,
/// `--path`: where to create the worktree instead of the `worktree-path`
/// template.
pub path: Option<&'a Path>,
pub clobber: bool,
pub verify: bool,
/// `--yes`: skip approval prompts and force past clobber checks.
pub yes: bool,
pub change_dir: bool,
pub format: SwitchFormat,
/// True when `current_or_recover` recovered from a deleted CWD. Suppresses
/// pre-switch hooks (no source worktree to run them against) and source
/// capture (`{{ base }}` / `{{ base_worktree_path }}` stay unset — there is
/// no live source worktree to read).
pub is_recovered: bool,
/// Error-enrichment context for a failed `plan_switch`, so the hint
/// suggests the full `wt switch … --execute=… -- …`. `None` for the picker,
/// which has no branch argument to embed in that suggested command.
pub suggestion_ctx: Option<SwitchSuggestionCtx>,
/// `--execute` command and its trailing args. Flows from `wt switch -x
/// <cmd>` on both the argument path and the picker (no branch given).
pub execute: Option<&'a str>,
pub execute_args: &'a [String],
/// Binary name for the shell-integration offer. `Some` only on the argument
/// path; the picker does not offer shell integration.
pub shell_integration_binary: Option<&'a str>,
}
impl SwitchPipeline<'_> {
/// Plan, approve, execute, and report the switch, then spawn its
/// background hooks and run any `--execute` command.
pub(crate) fn run(self) -> anyhow::Result<()> {
let Self {
repo,
config,
identifier,
create,
base,
path,
clobber,
verify,
yes,
change_dir,
format,
is_recovered,
suggestion_ctx,
execute,
execute_args,
shell_integration_binary,
} = self;
// Resolve the argument ahead of everything that describes the
// destination: the bare-repo offer's example paths, the `pre-switch`
// hooks' variables, and the plan itself. A `pr:N` argument reaches
// the forge here.
let target = SwitchTarget::resolve(repo, identifier, create, base)?;
// Kept past the move into `plan_switch`: a `pr:N` switch onto a branch
// that already has a worktree produces `SwitchResult::Existing`, which
// carries no PR identity of its own, and the hooks on that path should
// still see the same `pr_number` / `pr_url` as the creating run.
let ref_identity = target.ref_identity().cloned();
// Offer to fix worktree-path for bare repos with hidden directory names
// (.git, .bare) before anything reads worktree-path config.
if let Some(branch) = target.branch() {
offer_bare_repo_worktree_path_fix(repo, config, branch)?;
}
// Run pre-switch hooks before worktree creation. Skip when recovered —
// the source worktree is gone, nothing to run hooks against. `yes` is
// the single switch-wide flag, so the picker (no `--yes`) and the
// argument path gate `pre-switch` hooks identically.
let hooks_ran =
verify && !is_recovered && run_pre_switch_hooks(repo, config, &target, yes)?;
// A hook may have fetched or created what the argument names, and
// `repo` cached the refs and worktrees it read before the hook ran. So
// plan against a fresh repository, locating the argument again there.
let refreshed;
let (repo, target) = if hooks_ran {
refreshed = Repository::at(repo.discovery_path())?;
let target = SwitchTarget::locate(&refreshed, identifier, create, target.remote_ref)?;
(&refreshed, target)
} else {
(repo, target)
};
// Capture source (base) worktree identity BEFORE the switch, for
// post-switch {{ base }} / {{ base_worktree_path }}. Done here — after
// pre-switch hooks, before plan / approve / validate, none of which move
// the current worktree. Both entry points capture; `capture_switch_source`
// returns empty on the recovered path (no live source worktree).
let (source_branch, source_path) = capture_switch_source(repo, is_recovered);
// Validate and resolve the target branch.
let plan =
plan_switch(repo, target, create, base, path, clobber, config).map_err(|err| {
match suggestion_ctx {
Some(ref ctx) => match err.downcast::<GitError>() {
Ok(git_err) => GitError::WithSwitchSuggestion {
source: Box::new(git_err),
ctx: ctx.clone(),
}
.into(),
Err(err) => err,
},
None => err,
}
})?;
// "Approve at the Gate": collect and approve hooks upfront. Approval
// happens once at the command entry point. If the user declines, skip
// hooks but continue with the worktree operation. Switch hooks resolve
// their config from the invoking worktree — see `approve_switch_hooks`.
let (hooks_approved, hook_plan) = approve_switch_hooks(repo, config, &plan, yes, verify)?;
// Pre-flight: validate all templates before mutation (worktree
// creation). Catches syntax errors and undefined variables early so a
// broken template doesn't leave behind a half-created worktree that
// blocks re-running.
validate_switch_templates(repo, config, &plan, execute, execute_args, hooks_approved)?;
let (result, branch_info) =
match execute_switch(repo, plan, config, yes, hooks_approved, &hook_plan) {
Ok(result) => result,
Err(failure) => {
if format == SwitchFormat::Json
&& let Some((result, branch_info)) = failure.result.as_deref()
{
print_json(&SwitchJsonOutput::from_result(result, branch_info))?;
}
return Err(failure.error);
}
};
// Emit the result after all synchronous work, retaining the completed
// switch if a later directive, hook, or --execute operation fails.
let finish = (|| -> anyhow::Result<()> {
// Early exit for benchmarking time-to-first-output.
if std::env::var_os("WORKTRUNK_FIRST_OUTPUT").is_some() {
return Ok(());
}
// Show success message (temporal locality: immediately after the
// worktree operation). Returns the path to display in hooks when the
// user's shell won't be in the worktree, and shows the worktree-path
// hint on first --create (before the shell integration warning).
//
// `shell_cwd()` is where the user's shell stands: the process cwd,
// unless a parent `wt` passed its own down (an alias or hook body runs
// from the worktree root, so a nested switch would otherwise resolve
// the user to that root — #3723). When the shell's CWD was already
// gone when `wt` started, `startup_cwd()` never captured one and this
// reads as absent — fall back to `repo_path()` (the main worktree
// root). `current_worktree().root()` resolves against the Repository's
// discovery path, which is alive even after recovery, but we keep the
// same fallback for any pathological case where rev-parse fails.
let fallback_path = repo.repo_path()?.to_path_buf();
let cwd = shell_cwd().unwrap_or(fallback_path.clone());
let source_root = repo.current_worktree().root().unwrap_or(fallback_path);
let display_paths =
handle_switch_output(&result, &branch_info, change_dir, Some(&source_root), &cwd)?;
// Offer shell integration if not already installed/active (only shows
// the prompt/hint when shell integration isn't working). With
// --execute, show hints only — don't interrupt with a prompt. Skip when
// change_dir is false (the user opted out of cd, so shell integration
// is irrelevant) and on the picker path (no `binary_name`).
// Best-effort: don't fail the switch if the offer fails, but stop on
// cancellation.
if let Some(binary_name) = shell_integration_binary
&& change_dir
&& !is_shell_integration_active()
{
let skip_prompt = execute.is_some();
if let Err(err) = prompt_shell_integration(repo, config, binary_name, skip_prompt)
&& err.interrupt_signal().is_some()
{
return Err(err);
}
}
// Build template vars for base/target context (used by both hooks and
// --execute). "base" is the source worktree the user switched from (all
// switches), or the branch they branched from (creates). "target"
// matches the bare vars (the destination) — kept symmetric with
// pre-switch.
// `pr_number` / `pr_url` come from the resolved argument, not from
// `result` — a `pr:N` switch onto a branch that already has a worktree
// returns `SwitchResult::Existing`, which knows nothing about the PR.
let mut template_vars =
TemplateVars::for_post_switch(&result, &branch_info, &source_branch, &source_path);
if let Some(identity) = &ref_identity {
template_vars = template_vars.with_pr(Some(identity.number), Some(&identity.url));
}
let extra_vars = template_vars.as_extra_vars();
// Spawn background hooks after the success message.
// - post-switch: runs on ALL switches (shows "@ path" when the shell
// won't be there)
// - post-start: runs only when creating a NEW worktree
if hooks_approved {
spawn_switch_background_hooks(
config,
&result,
branch_info.branch.as_deref(),
yes,
&extra_vars,
display_paths.hooks.as_deref(),
&hook_plan,
)?;
}
// Execute the user command after post-start hooks have been spawned.
// Note: execute_args requires execute via clap's `requires` attribute.
if let Some(cmd) = execute {
// Build template context for expansion (includes base vars when
// creating).
let ctx = CommandContext::new(
repo,
config,
branch_info.branch.as_deref(),
result.path(),
yes,
);
// Compute only the vars the command actually names. The map is
// consumed by `expand_template` and nothing else — the child
// receives argv, never the context as JSON on stdin, and
// `--execute` renders no `-v` variables table. So a var the
// templates don't reference is a git subprocess whose result is
// thrown away.
//
// The union is complete: `validate_switch_templates` already
// parsed both positions against `ValidationScope::SwitchExecute`
// before the switch ran, so nothing reaching here is unparsable.
// No `alias_context_filter` — `args` is alias scope only, and
// `branch` (the implicit read behind `{{ vars.X }}`) is in
// `build_hook_context`'s unconditional cheap block.
let referenced = referenced_vars_for_templates(
std::iter::once(cmd).chain(execute_args.iter().map(String::as_str)),
);
let template_vars =
build_hook_context(&ctx, &extra_vars, VarScope::Referenced(&referenced))?;
// Every position is one argv element. Literal expansion preserves
// spaces, quotes, and shell metacharacters as data.
let program = template_vars.expand(
cmd,
ShellEscapeMode::Literal,
repo,
"--execute command",
)?;
let args: Result<Vec<_>, _> = execute_args
.iter()
.map(|arg| {
template_vars.expand(
arg,
ShellEscapeMode::Literal,
repo,
"--execute argument",
)
})
.collect();
let argv: Vec<String> = std::iter::once(program).chain(args?).collect();
// The header names where the program starts, which is the
// directory the switch selected and not the worktree the hooks
// announce (#4042).
execute_user_command(
&argv,
display_paths.execute.as_deref(),
&display_paths.execute_dir,
format == SwitchFormat::Json,
)?;
}
Ok(())
})();
if format == SwitchFormat::Json {
print_json(&SwitchJsonOutput::from_result(&result, &branch_info))?;
}
finish
}
}
/// Handle the switch command.
fn run_switch(
opts: SwitchOptions<'_>,
config: &mut UserConfig,
binary_name: &str,
) -> anyhow::Result<()> {
let SwitchOptions {
branch,
create,
base,
path,
execute,
execute_args,
yes,
clobber,
change_dir: change_dir_flag,
verify,
format,
} = opts;
let (repo, is_recovered) = current_or_recover().context("Failed to switch worktree")?;
// Resolve change_dir: explicit CLI flags > project config > global config > default (true)
// Now that we have the repo, we can resolve project-specific config.
let change_dir = change_dir_flag.unwrap_or_else(|| {
let project_id = repo.project_identifier().ok();
config.resolved(project_id.as_ref()).switch.cd()
});
// Build switch suggestion context for enriching error hints with --path/--execute/trailing args.
// Without this, errors like "branch already exists" would suggest `wt switch <branch>`
// instead of the full `wt switch <branch> --path=<dir> --execute=<cmd> -- <args>`.
// Dropping `--path` would point `--clobber` at the template's path instead.
let mut extra_flags = Vec::new();
if let Some(path) = path {
let escaped = shell_escape::unix::escape(path.to_string_lossy());
extra_flags.push(format!("--path={escaped}"));
}
if let Some(exec) = execute {
let escaped = shell_escape::unix::escape(exec.into());
extra_flags.push(format!("--execute={escaped}"));
}
let suggestion_ctx = (!extra_flags.is_empty()).then(|| SwitchSuggestionCtx {
extra_flags,
trailing_args: execute_args.to_vec(),
});
SwitchPipeline {
repo: &repo,
config,
identifier: branch,
create,
base,
path,
clobber,
verify,
yes,
change_dir,
format,
is_recovered,
suggestion_ctx,
execute,
execute_args,
shell_integration_binary: Some(binary_name),
}
.run()
}
/// Entry point for the `wt switch` command.
pub fn handle_switch_command(args: SwitchArgs, yes: bool) -> anyhow::Result<()> {
let verify = args.hooks.resolve();
// With no branch argument, `wt switch` opens a TUI picker — config
// deprecation warnings would render above the picker and push it down.
// They're still shown by other commands (`wt list`, `wt merge`, …).
if args.branch.is_none() {
worktrunk::config::suppress_warnings();
}
let mut config = UserConfig::load().context("Failed to load config")?;
// No branch argument: open interactive picker
let change_dir_flag = flag_pair(args.cd, args.no_cd);
let Some(branch) = args.branch else {
// No branch argument: open the interactive picker. `--execute`
// (and its trailing args) run against the picked worktree.
return crate::commands::handle_picker(
args.branches,
args.remotes,
args.prs,
change_dir_flag,
args.format,
args.execute.as_deref(),
&args.execute_args,
);
};
run_switch(
SwitchOptions {
branch: &branch,
create: args.create,
base: args.base.as_deref(),
path: args.path.as_deref(),
execute: args.execute.as_deref(),
execute_args: &args.execute_args,
yes,
clobber: args.clobber,
change_dir: change_dir_flag,
verify,
format: args.format,
},
&mut config,
&crate::binary_name(),
)
}
/// Validate all templates that will be expanded after worktree creation.
///
/// Catches syntax errors and undefined variable references *before* the
/// irreversible worktree creation, so a broken template doesn't leave behind
/// a worktree that blocks re-running the command.
///
/// This is a best-effort pre-flight check: it catches definite errors (syntax,
/// unknown variables) but cannot catch failures from conditional variables that
/// are absent at expansion time (e.g., `upstream` when no tracking is configured).
/// Such late failures propagate as normal errors — no panics.
///
/// ## Why only switch needs pre-flight validation
///
/// Switch is the only command where template failure after mutation creates a
/// **blocking half-state**: `wt switch -c <branch>` creates a worktree, then if
/// hook/--execute expansion fails, the worktree exists and the same command
/// can't be re-run (branch already exists). Other commands don't have this
/// problem:
///
/// - **Pre-operation hooks** (pre-merge, pre-remove, pre-commit) run before the
/// irreversible operation, so template errors abort cleanly.
/// - **Post-operation hooks** (post-merge, post-remove) run after the operation
/// completed successfully — template failure is a missed notification, not a
/// blocking state. The user can fix the template and run `wt hook` manually.
///
/// Hook templates checked here come from the invoking worktree's
/// `.config/wt.toml` — the same config the switch hooks run against — so the
/// templates validated are the ones that will actually be expanded.
///
/// Validates:
/// - `--execute` command template (if present)
/// - `--execute` trailing arg templates (if present)
/// - Hook templates (pre-start, post-start, post-switch) from user and project config
fn validate_switch_templates(
repo: &Repository,
config: &UserConfig,
plan: &SwitchPlan,
execute: Option<&str>,
execute_args: &[String],
hooks_approved: bool,
) -> anyhow::Result<()> {
// Validate --execute template and trailing args
if let Some(cmd) = execute {
validate_template(
cmd,
ValidationScope::SwitchExecute,
repo,
"--execute command",
)?;
for arg in execute_args {
validate_template(
arg,
ValidationScope::SwitchExecute,
repo,
"--execute argument",
)?;
}
}
// Validate hook templates only when hooks will actually run
if !hooks_approved {
return Ok(());
}
let project_config = repo.load_project_config()?;
let user_hooks = config.hooks(repo.project_identifier().ok().as_ref());
for &hook_type in switch_post_hook_types(plan.is_create()) {
let user_cfg = user_hooks.get(hook_type);
let proj_cfg = project_config.as_ref().and_then(|c| c.hooks.get(hook_type));
for (source, cfg) in [
(HookSource::User, user_cfg),
(HookSource::Project, proj_cfg),
] {
if let Some(cfg) = cfg {
for cmd in cfg.commands() {
// Skip full validation for templates referencing {{ vars.X }} —
// those values come from git config at execution time, after
// prior pipeline steps set them. Syntax is still checked by
// PreparedPipeline::validated.
if template_references_var(&cmd.template, "vars") {
continue;
}
let name = source.hook_label(hook_type, cmd.name.as_deref());
validate_template(
&cmd.template,
ValidationScope::Hook(hook_type),
repo,
&name,
)?;
}
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use worktrunk::testing::TestRepo;
/// Windows needs two representations of a deep worktree path: the
/// verbatim spelling that filesystem operations accept, and the
/// prefix-free canonical identity used for equality. Keep both sides of
/// that boundary pinned without asking Git to register an overlong
/// administrative `$GIT_DIR` path.
#[test]
#[cfg(windows)]
fn deep_worktree_keeps_operational_path_separate_from_identity() {
let temp = worktrunk::testing::tempdir().expect("temp dir");
let mut deep = temp.path().join("deep");
while deep.as_os_str().len() < 320 {
deep.push("nested-worktree-directory");
}
std::fs::create_dir_all(&deep).expect("create deep tree");
let operational = operational_worktree_path(deep.clone());
let identity = worktrunk::path::canonicalize_with_parents(&deep);
assert!(
operational.to_string_lossy().starts_with(r"\\?\"),
"dunce should retain the verbatim prefix: {}",
operational.display()
);
assert!(
!identity.to_string_lossy().starts_with(r"\\?\"),
"identity should remove the verbatim prefix: {}",
identity.display()
);
assert_ne!(operational, identity, "the representations should differ");
assert!(
same_worktree_path(&operational, &identity),
"canonical identity should still recognize one worktree"
);
}
#[test]
fn capture_switch_source_returns_empty_when_recovered() {
// When recovered from a deleted CWD, post-switch hooks must see empty
// `{{ base }}` / `{{ base_worktree_path }}` rather than the recovered
// ancestor's identity (typically the main worktree's branch/path).
let test = TestRepo::with_initial_commit();
let (branch, path) = capture_switch_source(&test.repo, true);
assert_eq!(branch, "");
assert_eq!(path, "");
}
#[test]
fn capture_switch_source_returns_branch_and_path_normally() {
// When not recovered, the helper reports the current worktree's
// identity. This guards against accidental regressions to the
// `is_recovered` gate (e.g., always returning empty).
let test = TestRepo::with_initial_commit();
let (branch, path) = capture_switch_source(&test.repo, false);
assert_eq!(branch, "main");
assert!(!path.is_empty(), "source_path should be the worktree root");
}
#[test]
fn choose_pr_forge_prefers_github_over_azure() {
// Mixed-remote setup: a repo with both a GitHub remote and an Azure
// DevOps remote falls through to GitHub. Operators with an explicit
// preference set `forge.platform`.
let test = TestRepo::with_initial_commit();
test.run_git(&["remote", "add", "origin", "https://github.com/myorg/myrepo"]);
test.run_git(&[
"remote",
"add",
"azure",
"https://dev.azure.com/myorg/proj/_git/myrepo",
]);
assert_eq!(choose_pr_forge(&test.repo).unwrap(), ForgeKind::GitHub);
}
#[test]
fn choose_pr_forge_azure_only() {
// Azure-only repo (no GitHub remote) uses Azure DevOps.
let test = TestRepo::with_initial_commit();
test.run_git(&[
"remote",
"add",
"origin",
"https://dev.azure.com/myorg/proj/_git/myrepo",
]);
assert_eq!(choose_pr_forge(&test.repo).unwrap(), ForgeKind::AzureDevOps);
}
#[test]
fn choose_pr_forge_no_recognised_remote() {
// Falls back to GitHub when no recognisable forge remote exists,
// preserving the existing error message from `gh`.
let test = TestRepo::with_initial_commit();
assert_eq!(choose_pr_forge(&test.repo).unwrap(), ForgeKind::GitHub);
}
#[test]
fn choose_pr_forge_platform_override_wins() {
// The bug worth covering: a mixed-remote repo where the user explicitly
// pinned `forge.platform = "azure-devops"`. Without the override, the
// GitHub remote would win — and the user has no way to redirect `pr:N`.
// A regression that drops the project-config read would flip this
// assertion to `GitHub`.
let test = TestRepo::with_initial_commit();
test.run_git(&["remote", "add", "origin", "https://github.com/myorg/myrepo"]);
test.run_git(&[
"remote",
"add",
"azure",
"https://dev.azure.com/myorg/proj/_git/myrepo",
]);
test.write_project_config("[forge]\nplatform = \"azure-devops\"\n");
assert_eq!(choose_pr_forge(&test.repo).unwrap(), ForgeKind::AzureDevOps);
}
#[test]
fn choose_pr_forge_platform_github_in_azure_only_repo() {
// Inverse override: Azure-only remotes but `forge.platform = "github"`.
// Verifies the config arm flips the inferred-from-remotes default.
let test = TestRepo::with_initial_commit();
test.run_git(&[
"remote",
"add",
"origin",
"https://dev.azure.com/myorg/proj/_git/myrepo",
]);
test.write_project_config("[forge]\nplatform = \"github\"\n");
assert_eq!(choose_pr_forge(&test.repo).unwrap(), ForgeKind::GitHub);
}
}