Skip to content

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

Clarify wt switch help text to address git switch confusion (#371)

Maximilian Roosb0ff39cb4fcc
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 0e03d89e5..0e1fdbe96 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -17,7 +17,7 @@ Change directory to a worktree, creating one if needed.
</picture>
</figure>
-Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+Worktrees are addressed by branch name; paths are computed from a template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
## Examples
@@ -64,6 +64,14 @@ wt switch ^ # Default branch worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
+## When wt switch fails
+
+- **Branch doesn't exist** — Use `--create`, or check `wt list --branches`
+- **Path occupied** — Another worktree is at the target path; switch to it or remove it
+- **Stale directory** — Use `--clobber` to remove a non-worktree directory at the target path
+
+To change which branch a worktree is on, use `git switch` inside that worktree.
+
## See also
- [wt select](@/select.md) — Interactive worktree selection
diff --git a/src/cli.rs b/src/cli.rs
index ae37eb3a0..56a8f2f7a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2257,7 +2257,7 @@ Missing a field that would be generally useful? Open an issue at https://github.
after_long_help = r#"Change directory to a worktree, creating one if needed.
<!-- demo: wt-switch.gif 1600x900 -->
-Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+Worktrees are addressed by branch name; paths are computed from a template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
## Examples
@@ -2304,6 +2304,14 @@ wt switch ^ # Default branch worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
+## When wt switch fails
+
+- **Branch doesn't exist** — Use `--create`, or check `wt list --branches`
+- **Path occupied** — Another worktree is at the target path; switch to it or remove it
+- **Stale directory** — Use `--clobber` to remove a non-worktree directory at the target path
+
+To change which branch a worktree is on, use `git switch` inside that worktree.
+
## See also
- [wt select](@/select.md) — Interactive worktree selection
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
index c887f4f56..98070f872 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -12,6 +12,7 @@ info:
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -27,7 +28,7 @@ Change directory to a worktree, creating one if needed.
</picture>
</figure>
-Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+Worktrees are addressed by branch name; paths are computed from a template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
## Examples
@@ -74,6 +75,14 @@ wt switch ^ # Default branch worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
+## When wt switch fails
+
+- **Branch doesn't exist** — Use `--create`, or check `wt list --branches`
+- **Path occupied** — Another worktree is at the target path; switch to it or remove it
+- **Stale directory** — Use `--clobber` to remove a non-worktree directory at the target path
+
+To change which branch a worktree is on, use `git switch` inside that worktree.
+
## See also
- [wt select](@/select.md) — Interactive worktree selection
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 1c0fbe140..cddaee85f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -12,6 +12,7 @@ info:
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -80,7 +81,8 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
Change directory to a worktree, creating one if needed.
-Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+Worktrees are addressed by branch name; paths are computed from a template. Unlike git switch, this navigates between worktrees rather than changing
+branches in place.
Examples
@@ -121,6 +123,14 @@ When creating a worktree, worktrunk:
wt switch ^ # Default branch worktree
wt switch --create fix --base=@ # Branch from current HEAD
+When wt switch fails
+
+- Branch doesn't exist — Use --create, or check wt list --branches
+- Path occupied — Another worktree is at the target path; switch to it or remove it
+- Stale directory — Use --clobber to remove a non-worktree directory at the target path
+
+To change which branch a worktree is on, use git switch inside that worktree.
+
See also
- wt select — Interactive worktree selection