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.mdindex 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 worktreewt 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 path2. Switches to new directory3. 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.-```bashwt switch feature # Existing branch → creates worktreewt switch --create feature # New branch and worktree@@ -53,12 +55,6 @@ wt switch ^ # Main worktreewt 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 selectiondiff --git a/src/cli.rs b/src/cli.rsindex 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 worktreewt 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 path2. Switches to new directory3. 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.-```consolewt switch feature # Existing branch → creates worktreewt switch --create feature # New branch and worktree@@ -2124,12 +2126,6 @@ wt switch ^ # Main worktreewt 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 selectiondiff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snapindex 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 worktreewt 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 path2. Switches to new directory3. 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.-```bashwt switch feature # Existing branch → creates worktreewt switch --create feature # New branch and worktree@@ -62,12 +64,6 @@ wt switch ^ # Main worktreewt 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 selectiondiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[1m[36m-v[0m, [1m[36m--verboseShow 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.[32mExamples@@ -79,20 +79,21 @@ Switches to a worktree, creating one if needed. Creating a worktree runs hooks.[2mwt switch --create new-feature # Create new branch and worktree[2mwt switch --create hotfix --base production-For interactive selection, use [2mwt select[0m.+[32mCreating a branch++The [2m--create[0m flag creates a new branch from the [2m--base[0m branch (defaults to default branch). Without [2m--create[0m, the branch must already exist.[32mCreating worktrees-When the target branch has no worktree, worktrunk:+If the branch already has a worktree, [2mwt switch[0m changes directories to it. Otherwise, it creates one.++When creating a worktree, worktrunk:1. Creates worktree at configured path2. Switches to new directory3. Runs post-create hooks (blocking)4. Spawns post-start hooks (background)-The [2m--create[0m flag creates a new branch from [2m--base[0m (defaults to the repository's default branch). Without [2m--create[0m, the branch must already-exist.-[2mwt switch feature # Existing branch → creates worktree[2mwt switch --create feature # New branch and worktree[2mwt switch --create fix --base release # New branch from release@@ -110,12 +111,6 @@ exist.[2mwt switch ^ # Main worktree[2mwt switch --create fix --base=@ # Branch from current HEAD-[32mArgument 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.-[32mSee also- wt select — Interactive worktree selection