Skip to content

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

Clarify switch command behavior and documentation

Maximilian Roos63e60adb7a69
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 59c73c135..e167955bf 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -96,15 +96,6 @@ If your remote's default branch has changed (e.g., renamed from master to main),
For full details on the detection mechanism, see `wt config cache --help`.
-## How does wt switch resolve branch names?
-
-Arguments resolve by checking the filesystem before git branches:
-
-1. Compute expected path from argument (using configured path template)
-2. If worktree exists at that path, switch to it
-3. Otherwise, look up as branch name
-4. If the path and branch resolve to different worktrees (e.g., `repo.foo/` tracks branch `bar`), the path takes precedence
-
## On Windows, `wt` conflicts with Windows Terminal
Windows Terminal uses `wt` as its command-line launcher, so running `wt` invokes Terminal instead of Worktrunk.
diff --git a/docs/content/remove.md b/docs/content/remove.md
index d3291b993..2fa4a9d9d 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -56,7 +56,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
-Arguments resolve by path first, then branch name. [Shortcuts](@/switch.md#shortcuts): `@` (current), `-` (previous), `^` (main worktree).
+Arguments use path-first resolution—see [wt switch](@/switch.md#argument-resolution). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).
## See also
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 016cb9fb4..408fd9ec0 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -8,9 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
-Switches to a worktree, creating one if needed.
-
-With `--create`, creates a new branch based off `--base` (defaults to default branch) and runs [hooks](@/hook.md).
+Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
## Examples
@@ -25,18 +23,19 @@ For interactive selection, use [`wt select`](@/select.md).
## Creating worktrees
-With `--create`, worktrunk:
+When the target branch has no worktree, worktrunk:
+
+1. Creates worktree at configured path
+2. Runs [post-create hooks](@/hook.md#post-create) (blocking)
+3. Switches to new directory
+4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-1. Creates branch from `--base` (defaults to default branch)
-2. Creates worktree at configured path
-3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
-4. Switches to new directory
-5. Spawns [post-start hooks](@/hook.md#post-start) (background)
+The `--create` flag creates a new branch from `--base` (defaults to default branch). Without `--create`, the branch must already exist.
```bash
-wt switch --create api-refactor
-wt switch --create fix --base release-2.0
-wt switch --create docs --execute "code ."
+wt switch feature # Existing branch → creates worktree
+wt switch --create feature # New branch and worktree
+wt switch --create fix --base release # New branch from release
wt switch --create temp --no-verify # Skip hooks
```
@@ -54,6 +53,16 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
+## Argument resolution
+
+Arguments resolve by checking the filesystem before git branches:
+
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, look up as branch name
+
+If the path and branch resolve to different worktrees (e.g., `repo.foo/` tracks branch `bar`), the path takes precedence.
+
## See also
- [wt select](@/select.md) — Interactive worktree selection
diff --git a/src/cli.rs b/src/cli.rs
index b74679b97..aa013e54e 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2009,9 +2009,8 @@ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_st
},
/// Switch to a worktree
- #[command(after_long_help = r#"Switches to a worktree, creating one if needed.
-
-With `--create`, creates a new branch based off `--base` (defaults to default branch) and runs [hooks](@/hook.md).
+ #[command(
+ after_long_help = r#"Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
## Examples
@@ -2026,18 +2025,19 @@ For interactive selection, use [`wt select`](@/select.md).
## Creating worktrees
-With `--create`, worktrunk:
+When the target branch has no worktree, worktrunk:
+
+1. Creates worktree at configured path
+2. Runs [post-create hooks](@/hook.md#post-create) (blocking)
+3. Switches to new directory
+4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-1. Creates branch from `--base` (defaults to default branch)
-2. Creates worktree at configured path
-3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
-4. Switches to new directory
-5. Spawns [post-start hooks](@/hook.md#post-start) (background)
+The `--create` flag creates a new branch from `--base` (defaults to default branch). Without `--create`, the branch must already exist.
```console
-wt switch --create api-refactor
-wt switch --create fix --base release-2.0
-wt switch --create docs --execute "code ."
+wt switch feature # Existing branch → creates worktree
+wt switch --create feature # New branch and worktree
+wt switch --create fix --base release # New branch from release
wt switch --create temp --no-verify # Skip hooks
```
@@ -2055,13 +2055,24 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
+## Argument resolution
+
+Arguments resolve by checking the filesystem before git branches:
+
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, look up as branch name
+
+If the path and branch resolve to different worktrees (e.g., `repo.foo/` tracks branch `bar`), the path takes precedence.
+
## See also
- [wt select](@/select.md) — Interactive worktree selection
- [wt list](@/list.md) — View all worktrees
- [wt remove](@/remove.md) — Delete worktrees when done
- [wt merge](@/merge.md) — Integrate changes back to main
-"#)]
+"#
+ )]
Switch {
/// Branch or worktree name
///
@@ -2155,7 +2166,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
Removal runs in the background by default (returns immediately). Logs are written to `.git/wt-logs/{branch}-remove.log`. Use `--no-background` to run in the foreground.
-Arguments resolve by path first, then branch name. [Shortcuts](@/switch.md#shortcuts): `@` (current), `-` (previous), `^` (main worktree).
+Arguments use path-first resolution—see [wt switch](@/switch.md#argument-resolution). Shortcuts: `@` (current), `-` (previous), `^` (main worktree).
## See also
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 2ccdcb210..2ce8cdab0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -99,7 +99,7 @@ Use -D to force-delete branches with unmerged changes. Use --no-dele
Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --no-background to run
in the foreground.
-Arguments resolve by path first, then branch name. Shortcuts: @ (current), - (previous), ^ (main worktree).
+Arguments use path-first resolution—see wt switch. Shortcuts: @ (current), - (previous), ^ (main worktree).
See also
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 2143b6184..9b48c6e5c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -67,9 +67,7 @@ Usage: wt switch [OPTIONS] <BRANCH>
-v, --verbose
Show commands and debug info
-Switches to a worktree, creating one if needed.
-
-With --create, creates a new branch based off --base (defaults to default branch) and runs hooks.
+Switches to a worktree, creating one if needed. Creating a worktree runs hooks.
Examples
@@ -82,17 +80,18 @@ For interactive selection, use `wt select`.
Creating worktrees
-With --create, worktrunk:
+When the target branch has no worktree, worktrunk:
+
+1. Creates worktree at configured path
+2. Runs post-create hooks (blocking)
+3. Switches to new directory
+4. Spawns post-start hooks (background)
-1. Creates branch from --base (defaults to default branch)
-2. Creates worktree at configured path
-3. Runs post-create hooks (blocking)
-4. Switches to new directory
-5. Spawns post-start hooks (background)
+The --create flag creates a new branch from --base (defaults to default branch). Without --create, the branch must already exist.
- wt switch --create api-refactor
- wt switch --create fix --base release-2.0
- wt switch --create docs --execute "code ."
+ wt switch feature # Existing branch → creates worktree
+ wt switch --create feature # New branch and worktree
+ wt switch --create fix --base release # New branch from release
wt switch --create temp --no-verify # Skip hooks
Shortcuts
@@ -107,6 +106,16 @@ With --create, worktrunk:
wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
+Argument resolution
+
+Arguments resolve by checking the filesystem before git branches:
+
+1. Compute expected path from argument (using configured path template)
+2. If worktree exists at that path, switch to it
+3. Otherwise, look up as branch name
+
+If the path and branch resolve to different worktrees (e.g., repo.foo/ tracks branch bar), the path takes precedence.
+
See also
- wt select — Interactive worktree selection