Skip to content

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

feat: support path-based switch for detached worktrees (#1680)

Maximilian Roose1e47a3b04cc
diff --git a/docs/content/remove.md b/docs/content/remove.md
index 7c4cbc404..a2807579e 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -81,7 +81,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
## Detached HEAD worktrees
-Detached worktrees have no branch name, so they can't be removed by branch. Pass the worktree path instead: `wt remove /path/to/worktree`.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
## See also
@@ -99,7 +99,7 @@ Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=g>Arguments:</span></b>
<span class=c>[BRANCHES]...</span>
- Branch name or path [default: current]
+ Branch name [default: current]
<b><span class=g>Options:</span></b>
<b><span class=c>--no-delete-branch</span></b>
diff --git a/skills/worktrunk/reference/remove.md b/skills/worktrunk/reference/remove.md
index 02d22f388..688d89156 100644
--- a/skills/worktrunk/reference/remove.md
+++ b/skills/worktrunk/reference/remove.md
@@ -72,7 +72,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
## Detached HEAD worktrees
-Detached worktrees have no branch name, so they can't be removed by branch. Pass the worktree path instead: `wt remove /path/to/worktree`.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
## Command reference
@@ -84,7 +84,7 @@ Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=g>Arguments:</span></b>
<span class=c>[BRANCHES]...</span>
- Branch name or path [default: current]
+ Branch name [default: current]
<b><span class=g>Options:</span></b>
<b><span class=c>--no-delete-branch</span></b>
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index a3319ceca..2132045c3 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -820,7 +820,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
## Detached HEAD worktrees
-Detached worktrees have no branch name, so they can't be removed by branch. Pass the worktree path instead: `wt remove /path/to/worktree`.
+Detached worktrees have no branch name. Pass the worktree path instead: `wt remove /path/to/worktree`. `wt switch /path/to/worktree` also works.
## See also
@@ -828,7 +828,7 @@ Detached worktrees have no branch name, so they can't be removed by branch. Pass
- [`wt list`](@/list.md) — View all worktrees
"#)]
Remove {
- /// Branch name or path [default: current]
+ /// Branch name [default: current]
#[arg(add = crate::completion::local_branches_completer())]
branches: Vec<String>,
diff --git a/src/commands/picker/mod.rs b/src/commands/picker/mod.rs
index 8e00e801d..7bd8b5c6b 100644
--- a/src/commands/picker/mod.rs
+++ b/src/commands/picker/mod.rs
@@ -372,11 +372,21 @@ pub fn handle_picker(
PickerAction::Create | PickerAction::Switch => {
let should_create = matches!(action, PickerAction::Create);
- // Get branch name: from query if creating new, from selected item if switching
- let selected_name = out
- .selected_items
- .first()
- .map(|item| item.output().to_string());
+ // Get branch name: from query if creating new, from selected item if switching.
+ // For detached worktrees, use the path (same as `wt switch /path` from CLI).
+ let selected = out.selected_items.first();
+ let selected_name = selected.map(|item| {
+ if !should_create
+ && let Some(data) = item
+ .as_any()
+ .downcast_ref::<WorktreeSkimItem>()
+ .and_then(|s| s.item.worktree_data())
+ .filter(|d| d.detached)
+ {
+ return data.path.to_string_lossy().into_owned();
+ }
+ item.output().to_string()
+ });
let query = out.query.trim().to_string();
let identifier = resolve_identifier(&action, query, selected_name)?;
diff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rs
index 6925c862b..41adfa302 100644
--- a/src/commands/worktree/switch.rs
+++ b/src/commands/worktree/switch.rs
@@ -613,6 +613,38 @@ pub fn plan_switch(
None => {}
}
+ // Phase 2b: Path-based fallback for detached worktrees.
+ // If the argument looks like a path (not a branch name), try to find a worktree there.
+ if !create {
+ let candidate = Path::new(branch);
+ let abs_path = if candidate.is_absolute() {
+ Some(candidate.to_path_buf())
+ } else if candidate.components().count() > 1 {
+ // Relative path with directory separators (e.g., "../repo.feature").
+ // Single-component names are ambiguous with branch names (already tried in Phase 2).
+ std::env::current_dir().ok().map(|cwd| cwd.join(candidate))
+ } else {
+ None
+ };
+ if let Some(abs_path) = abs_path
+ && let Some((path, wt_branch)) = repo.worktree_at_path(&abs_path)?
+ {
+ let canonical = canonicalize(&path).unwrap_or_else(|_| path.clone());
+ // For detached worktrees, use the directory name as the branch identifier
+ let branch = wt_branch.unwrap_or_else(|| {
+ canonical
+ .file_name()
+ .map(|n| n.to_string_lossy().into_owned())
+ .unwrap_or_else(|| "(detached)".to_string())
+ });
+ return Ok(SwitchPlan::Existing {
+ path: canonical,
+ branch,
+ new_previous,
+ });
+ }
+ }
+
// Phase 3: Compute expected path (only needed for create)
let expected_path = compute_worktree_path(repo, &target.branch, config)?;
diff --git a/tests/integration_tests/switch.rs b/tests/integration_tests/switch.rs
index eed5195e3..d28a517c4 100644
--- a/tests/integration_tests/switch.rs
+++ b/tests/integration_tests/switch.rs
@@ -994,6 +994,24 @@ fn test_switch_error_path_occupied_detached(repo: TestRepo) {
snapshot_switch_with_directive_file("switch_error_path_occupied_detached", &repo, &["feature"]);
}
+/// Switch to a detached worktree by path (#1661).
+#[rstest]
+fn test_switch_detached_worktree_by_path(mut repo: TestRepo) {
+ repo.add_worktree("feature-detached");
+ repo.detach_head_in_worktree("feature-detached");
+
+ let worktree_path = repo
+ .worktree_path("feature-detached")
+ .to_string_lossy()
+ .to_string();
+
+ snapshot_switch_with_directive_file(
+ "switch_detached_worktree_by_path",
+ &repo,
+ &[&worktree_path],
+ );
+}
+
///
/// When the main worktree (repo root) has been switched to a feature branch via
/// `git checkout feature`, `wt switch main` should error with a helpful message
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index f7d64593d..59696c7ce 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -39,7 +39,7 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
Arguments:
[BRANCHES]...
- Branch name or path [default: current]
+ Branch name [default: current]
Options:
--no-delete-branch
@@ -136,7 +136,7 @@ Removal runs in the background by default (returns immediately). Logs are writte
Detached HEAD worktrees
-Detached worktrees have no branch name, so they can't be removed by branch. Pass the worktree path instead: wt remove /path/to/worktree.
+Detached worktrees have no branch name. Pass the worktree path instead: wt remove /path/to/worktree. wt switch /path/to/worktree also works.
See also
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
index 2494b1437..164f3f509 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
@@ -36,7 +36,7 @@ wt remove - Remove worktree; delete branch if merged
Usage: wt remove [OPTIONS] [BRANCHES]...
Arguments:
- [BRANCHES]... Branch name or path [default: current]
+ [BRANCHES]... Branch name [default: current]
Options:
--no-delete-branch Keep branch after removal
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_detached_worktree_by_path.snap b/tests/snapshots/integration__integration_tests__switch__switch_detached_worktree_by_path.snap
new file mode 100644
index 000000000..cf528dfb6
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__switch__switch_detached_worktree_by_path.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/switch.rs
+info:
+ program: wt
+ args:
+ - switch
+ - /private/var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpj2sTWR/repo.feature-detached
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ PATH: "[PATH]"
+ PSModulePath: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_DIRECTIVE_FILE: "[DIRECTIVE_FILE]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+▲ Branch-worktree mismatch: repo.feature-detached @ _REPO_.feature-detached, expected @ _REPO_.repo.feature-detached ⚑
+○ Switched to worktree for repo.feature-detached @ _REPO_.feature-detached