Skip to content

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.md
index 8422164f9..74060ee41 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -6,109 +6,90 @@ weight = 10
group = "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:
```bash
wt 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 hooks
wt 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 worktree
wt 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