Skip to content

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

Improve wt switch documentation clarity (#247)

Maximilian Roos8cda18587de3
diff --git a/docs/content/switch.md b/docs/content/switch.md
index cd5262eb9..06a338531 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -8,7 +8,7 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
-Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
## Examples
@@ -19,19 +19,21 @@ wt switch --create new-feature # Create new branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](@/select.md).
+## Creating a branch
+
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
## Creating worktrees
-When the target branch has no worktree, worktrunk:
+If the branch already has a worktree, `wt switch` changes directories to it. Otherwise, it creates one.
+
+When creating a worktree, worktrunk:
1. Creates worktree at configured path
2. Switches to new directory
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
-
```bash
wt switch feature # Existing branch → creates worktree
wt switch --create feature # New branch and worktree
@@ -53,12 +55,6 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-## Argument resolution
-
-Switches to the branch's worktree if one exists, otherwise creates one at the expected path.
-
-If the expected path is occupied by a different branch's worktree, an error is raised.
-
## See also
- [wt select](@/select.md) — Interactive worktree selection
diff --git a/src/cli.rs b/src/cli.rs
index ac2fb15d5..c328fda01 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2079,7 +2079,7 @@ When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_chang
/// Switch to a worktree
#[command(
- after_long_help = r#"Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+ after_long_help = r#"Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
## Examples
@@ -2090,19 +2090,21 @@ wt switch --create new-feature # Create new branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](@/select.md).
+## Creating a branch
+
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
## Creating worktrees
-When the target branch has no worktree, worktrunk:
+If the branch already has a worktree, `wt switch` changes directories to it. Otherwise, it creates one.
+
+When creating a worktree, worktrunk:
1. Creates worktree at configured path
2. Switches to new directory
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
-
```console
wt switch feature # Existing branch → creates worktree
wt switch --create feature # New branch and worktree
@@ -2124,12 +2126,6 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-## Argument resolution
-
-Switches to the branch's worktree if one exists, otherwise creates one at the expected path.
-
-If the expected path is occupied by a different branch's worktree, an error is raised.
-
## 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 714e76290..877f48459 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -17,7 +17,7 @@ exit_code: 0
----- stdout -----
<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
-Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
## Examples
@@ -28,19 +28,21 @@ wt switch --create new-feature # Create new branch and worktree
wt switch --create hotfix --base production
```
-For interactive selection, use [`wt select`](@/select.md).
+## Creating a branch
+
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
## Creating worktrees
-When the target branch has no worktree, worktrunk:
+If the branch already has a worktree, `wt switch` changes directories to it. Otherwise, it creates one.
+
+When creating a worktree, worktrunk:
1. Creates worktree at configured path
2. Switches to new directory
3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
4. Spawns [post-start hooks](@/hook.md#post-start) (background)
-The `--create` flag creates a new branch from `--base` (defaults to the repository's default branch). Without `--create`, the branch must already exist.
-
```bash
wt switch feature # Existing branch → creates worktree
wt switch --create feature # New branch and worktree
@@ -62,12 +64,6 @@ wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
```
-## Argument resolution
-
-Switches to the branch's worktree if one exists, otherwise creates one at the expected path.
-
-If the expected path is occupied by a different branch's worktree, an error is raised.
-
## 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 14c55dbc7..1cdf1aedd 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -70,7 +70,7 @@ Usage: wt switch [OPTIONS] <BRANCH>
-v, --verbose
Show commands and debug info
-Switches to a worktree, creating one if needed. Creating a worktree runs hooks.
+Change directory to a worktree, creating one if needed. Creating a worktree runs hooks.
Examples
@@ -79,20 +79,21 @@ Switches to a worktree, creating one if needed. Creating a worktree runs hooks.
wt switch --create new-feature # Create new branch and worktree
wt switch --create hotfix --base production
-For interactive selection, use wt select.
+Creating a branch
+
+The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist.
Creating worktrees
-When the target branch has no worktree, worktrunk:
+If the branch already has a worktree, wt switch changes directories to it. Otherwise, it creates one.
+
+When creating a worktree, worktrunk:
1. Creates worktree at configured path
2. Switches to new directory
3. Runs post-create hooks (blocking)
4. Spawns post-start hooks (background)
-The --create flag creates a new branch from --base (defaults to the repository's default branch). Without --create, the branch must already
-exist.
-
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
@@ -110,12 +111,6 @@ exist.
wt switch ^ # Main worktree
wt switch --create fix --base=@ # Branch from current HEAD
-Argument resolution
-
-Switches to the branch's worktree if one exists, otherwise creates one at the expected path.
-
-If the expected path is occupied by a different branch's worktree, an error is raised.
-
See also
- wt select — Interactive worktree selection