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.mdindex 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 TerminalWindows 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.mdindex 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-branchRemoval 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 alsodiff --git a/docs/content/switch.md b/docs/content/switch.mdindex 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 releasewt switch --create temp --no-verify # Skip hooks```@@ -54,6 +53,16 @@ wt switch ^ # Main worktreewt 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 selectiondiff --git a/src/cli.rs b/src/cli.rsindex 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 releasewt switch --create temp --no-verify # Skip hooks```@@ -2055,13 +2055,24 @@ wt switch ^ # Main worktreewt 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-branchRemoval 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 alsodiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex 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 [2m-D[0m to force-delete branches with unmerged changes. Use [2m--no-deleRemoval runs in the background by default (returns immediately). Logs are written to [2m.git/wt-logs/{branch}-remove.log[0m. Use [2m--no-background[0m to runin the foreground.-Arguments resolve by path first, then branch name. Shortcuts: [2m@[0m (current), [2m-[0m (previous), [2m^[0m (main worktree).+Arguments use path-first resolution—see wt switch. Shortcuts: [2m@[0m (current), [2m-[0m (previous), [2m^[0m (main worktree).[32mSee alsodiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: [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.--With [2m--create[0m, creates a new branch based off [2m--base[0m (defaults to default branch) and runs hooks.+Switches to a worktree, creating one if needed. Creating a worktree runs hooks.[32mExamples@@ -82,17 +80,18 @@ For interactive selection, use `wt select`.[32mCreating worktrees-With [2m--create[0m, 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 [2m--base[0m (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 [2m--create[0m flag creates a new branch from [2m--base[0m (defaults to default branch). Without [2m--create[0m, the branch must already exist.- [2mwt switch --create api-refactor- [2mwt switch --create fix --base release-2.0- [2mwt switch --create docs --execute "code ."+ [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[2mwt switch --create temp --no-verify # Skip hooks[32mShortcuts@@ -107,6 +106,16 @@ With [2m--create[0m, worktrunk:[2mwt switch ^ # Main worktree[2mwt switch --create fix --base=@ # Branch from current HEAD+[32mArgument 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., [2mrepo.foo/[0m tracks branch [2mbar[0m), the path takes precedence.+[32mSee also- wt select — Interactive worktree selection