Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Refactor `wt switch` docs for clarity
Maximilian Roosc846d225ecdc
diff --git a/docs/content/switch.md b/docs/content/switch.mdindex 8422164f9..74060ee41 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -6,109 +6,90 @@ weight = 10group = "Commands"+++-## Operation--### Worktree resolution--Arguments are resolved using **path-first lookup**:--1. Compute the expected path for the argument (using the configured path template)-2. If a worktree exists at that path, switch to it (regardless of what branch it's on)-3. Otherwise, treat the argument as a branch name--**Example**: If `repo.foo/` exists but is on branch `bar`:--- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)-- `wt switch bar` also works (falls back to branch lookup)--### Switching to Existing Worktree--- If worktree exists at expected path or for branch, changes directory via shell integration-- No hooks run-- No branch creation--### Creating New Worktree (`--create`)--1. Creates new branch (defaults to current default branch as base)-2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)-3. Runs post-create hooks sequentially (blocking)-4. Shows success message-5. Spawns post-start hooks in background (non-blocking)-6. Changes directory to new worktree via shell integration--## Hooks--### post-create (sequential, blocking)--- Run after worktree creation, before success message-- Typically: `npm install`, `cargo build`, setup tasks-- Failures block the operation-- Skip with `--no-verify`--### post-start (parallel, background)--- Spawned after success message shown-- Typically: dev servers, file watchers, editors-- Run in background, failures logged but don't block-- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`-- Skip with `--no-verify`--**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`--**Security:** Commands from project hooks require approval on first run.-Approvals are saved to user config. Use `--force` to bypass prompts.-See `wt config approvals --help`.+Navigate between worktrees or create new ones. Switching to an existing worktree is just a directory change. With `--create`, a new branch and worktree are created, and hooks run.## Examples-Switch to existing worktree:+Switch to an existing worktree:```bash-wt switch feature-branch+wt switch feature-auth```-Create new worktree from main:+Create a new worktree for a fresh branch:```bashwt switch --create new-feature```-Switch to previous worktree:+Create from a specific base branch:```bash-wt switch -+wt switch --create hotfix --base production```-Create from specific base:+Switch to the previous worktree (like `cd -`):```bash-wt switch --create hotfix --base production+wt switch -```-Create and run command:+## Creating Worktrees++The `--create` flag (or `-c`) creates a new branch from the default branch (or `--base`), sets up a worktree at `../{repo}.{branch}`, runs [post-create hooks](/hooks/#post-create) synchronously, then spawns [post-start hooks](/hooks/#post-start) in the background before switching to the new directory.```bash-wt switch --create docs --execute "code ."-```+# Create from main (default)+wt switch --create api-refactor-Skip hooks during creation:+# Create from a specific branch+wt switch --create emergency-fix --base release-2.0-```bash+# Create and open in editor+wt switch --create docs --execute "code ."++# Skip all hookswt switch --create temp --no-verify```## Shortcuts-Use `@` for current HEAD, `-` for previous, `^` for main:+Special symbols for common targets:++| Shortcut | Meaning |+|----------|---------|+| `-` | Previous worktree (like `cd -`) |+| `@` | Current branch's worktree |+| `^` | Default branch (main/master) |```bash-wt switch @ # Switch to current branch's worktree-wt switch - # Switch to previous worktree-wt switch --create new-feature --base=^ # Branch from main (default)+wt switch - # Go back to previous worktree+wt switch ^ # Switch to main worktreewt switch --create bugfix --base=@ # Branch from current HEAD-wt remove @ # Remove current worktree```+## Hooks++When creating a worktree (`--create`), hooks run in this order:++1. **post-create** — Blocking, sequential. Typically: `npm install`, `cargo build`+2. **post-start** — Background, parallel. Typically: dev servers, file watchers++See [Hooks](/hooks/) for configuration details.++## How Arguments Are Resolved++Arguments resolve using **path-first lookup**:++1. Compute the expected path for the argument (using the configured path template)+2. If a worktree exists at that path, switch to it (regardless of what branch it's on)+3. Otherwise, treat the argument as a branch name++**Example**: If `repo.foo/` exists but is on branch `bar`:++- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)+- `wt switch bar` also works (falls back to branch lookup)+---## Command Reference