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.mdindex 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 worktreewt 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 selectiondiff --git a/src/cli.rs b/src/cli.rsindex 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 worktreewt 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 selectiondiff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snapindex 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: warnSOURCE_DATE_EPOCH: "1735776000"WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"---success: trueexit_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 worktreewt 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 selectiondiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: warnSOURCE_DATE_EPOCH: "1735776000"WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"---success: trueexit_code: 0@@ -80,7 +81,8 @@ Usage: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m [1m[36m[--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 [2mgit switch[0m, this navigates between worktrees rather than changing+branches in place.[32mExamples@@ -121,6 +123,14 @@ When creating a worktree, worktrunk:[2mwt switch ^ # Default branch worktree[2mwt switch --create fix --base=@ # Branch from current HEAD+[32mWhen wt switch fails++- [1mBranch doesn't exist[0m — Use [2m--create[0m, or check [2mwt list --branches+- [1mPath occupied[0m — Another worktree is at the target path; switch to it or remove it+- [1mStale directory[0m — Use [2m--clobber[0m to remove a non-worktree directory at the target path++To change which branch a worktree is on, use [2mgit switch[0m inside that worktree.+[32mSee also- wt select — Interactive worktree selection