Skip to content

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

docs: refactor command pages for consistency and auto-sync

Maximilian Roosf80d87b2290e
diff --git a/README.md b/README.md
index 9f333cd7e..51d7c43f9 100644
--- a/README.md
+++ b/README.md
@@ -503,111 +503,92 @@ Global Options:
-v, --verbose
Show commands and debug info
-```
-
-### 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
+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.
-- 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`.
+```
### 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)
+
<!-- END AUTO-GENERATED -->
</details>
@@ -664,70 +645,62 @@ Global Options:
-v, --verbose
Show commands and debug info
-```
-
-### Operation
-
-Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
+Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
-#### Commit
+```
-Uncommitted changes are staged and committed with LLM commit message.
-Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
+### Examples
-#### Squash
+Merge current worktree into main:
-Multiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.
-Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
+```bash
+wt merge
+```
-#### Rebase
+Keep the worktree after merging:
-Branch is rebased onto target. Conflicts abort the merge immediately.
+```bash
+wt merge --no-remove
+```
-#### Hooks
+Preserve commit history (no squash):
-Pre-merge commands run after rebase (failures abort). Post-merge commands
-run after cleanup (failures logged). Skip all with `--no-verify`.
+```bash
+wt merge --no-squash
+```
-#### Push
+Skip hooks and approval prompts:
-Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+```bash
+wt merge --no-verify --force
+```
-#### Cleanup
+### The Pipeline
-Worktree and branch are removed. Skip with `--no-remove`.
+`wt merge` runs these steps in order:
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
-**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`.
+2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-### Examples
+3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
-Basic merge to main:
+4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
-```bash
-wt merge
-```
+5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
-Merge without squashing:
+6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
-```bash
-wt merge --no-squash
-```
+7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
-Keep worktree after merging:
+### Hooks
-```bash
-wt merge --no-remove
-```
+When merging, hooks run in this order:
-Skip all hooks:
+1. **pre-merge** — After rebase, before push. Failures abort the merge.
+2. **post-merge** — After cleanup. Failures are logged but don't abort.
-```bash
-wt merge --no-verify
-```
+The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
<!-- END AUTO-GENERATED -->
@@ -769,66 +742,9 @@ Global Options:
-v, --verbose
Show commands and debug info
-```
-
-### Operation
+Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
-Removes worktree directory, git metadata, and branch. Requires clean working tree.
-
-#### No arguments (remove current)
-
-- Removes current worktree and switches to main worktree
-- In main worktree: switches to default branch
-
-#### By name (remove specific)
-
-- Removes specified worktree(s) and branches
-- Current worktree removed last (switches to main first)
-
-#### Worktree resolution
-
-Arguments are resolved to worktrees 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
-
-**Conflict detection**: If path `repo.foo/` has a worktree on branch `bar`, but
-branch `foo` has a different worktree at `repo.bar/`, an error is raised.
-
-**Special arguments**:
-
-- `@` - current worktree (by path, works in detached HEAD)
-- `-` - previous worktree (from switch history)
-- `^` - main worktree
-
-#### Branch deletion
-
-By default, branches are deleted only when their content is already in the target branch:
-
-- no changes beyond the common ancestor — `git diff --name-only target...branch` is empty:
- no files changed between the merge base of `target`/`branch` and the tip of `branch`.
-- same content as target — `git rev-parse branch^{tree}` equals `git rev-parse target^{tree}`:
- both branches point at the same tracked-files snapshot (tree), even if the commits differ.
-
-This handles workflows where PRs are squash-merged or rebased, which don't preserve
-commit ancestry but do integrate the content. Use `-D` to delete unintegrated
-branches, or `--no-delete-branch` to always keep branches.
-
-#### Background removal (default)
-
-- Returns immediately for continued work
-- Logs: `.git/wt-logs/{branch}-remove.log`
-- Use `--no-background` for foreground (blocking)
-
-#### Cleanup
-
-Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
+```
### Examples
@@ -838,13 +754,13 @@ Remove current worktree and branch:
wt remove
```
-Remove specific worktree and branch:
+Remove a specific worktree:
```bash
wt remove feature-branch
```
-Remove worktree but keep branch:
+Keep the branch after removing the worktree:
```bash
wt remove --no-delete-branch feature-branch
@@ -856,17 +772,38 @@ Remove multiple worktrees:
wt remove old-feature another-branch
```
-Remove in foreground (blocking):
+Force-delete an unmerged branch:
```bash
-wt remove --no-background feature-branch
+wt remove -D experimental
```
-Switch to default in main:
+### Branch Deletion
-```bash
-wt remove # (when already in main worktree)
-```
+By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+
+The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+
+### Background Removal
+
+Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+
+The `--no-background` flag runs removal in the foreground (blocking).
+
+### 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
+- `wt remove bar` also works (falls back to branch lookup)
+
+**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
<!-- END AUTO-GENERATED -->
@@ -918,99 +855,122 @@ Global Options:
-v, --verbose
Show commands and debug info
+Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
+
```
-### Columns
+### Examples
-- **Branch:** Branch name
-- **Status:** Quick status symbols (see Status Symbols below)
-- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
-- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
-- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)
-- **Path:** Worktree directory location
-- **Remote⇅:** Commits ahead⇡/behind⇣ relative to tracking branch (e.g. `origin/branch`)
-- **CI** (`--full`): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
- - `●` **passed** (green) - All checks passed
- - `●` **running** (blue) - Checks in progress
- - `●` **failed** (red) - Checks failed
- - `●` **conflicts** (yellow) - Merge conflicts with base
- - `●` **no-ci** (gray) - PR/MR or workflow found but no checks configured
- - **(blank)** - No PR/MR or workflow found, or `gh`/`glab` CLI unavailable
- - **(dimmed)** - Stale: unpushed local changes differ from PR/MR head
-- **Commit:** Short commit hash (8 chars)
-- **Age:** Time since last commit (relative)
-- **Message:** Last commit message (truncated)
+List all worktrees:
-### Status Symbols
+```bash
+wt list
+```
-Order: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
-
-- `+` Staged files (ready to commit)
-- `!` Modified files (unstaged changes)
-- `?` Untracked files present
-- `✖` **Merge conflicts** - unresolved conflicts in working tree (fix before continuing)
-- `⊘` **Would conflict** - merging into main would fail
-- `≡` Working tree matches main (identical contents, regardless of commit history)
-- `_` No commits (no commits ahead AND no uncommitted changes)
-- `↻` Rebase in progress
-- `⋈` Merge in progress
-- `↑` Ahead of main branch
-- `↓` Behind main branch
-- `↕` Diverged (both ahead and behind main)
-- `⇡` Ahead of remote tracking branch
-- `⇣` Behind remote tracking branch
-- `⇅` Diverged (both ahead and behind remote)
-- `⎇` Branch indicator (shown for branches without worktrees)
-- `⌫` Prunable worktree (directory missing, can be pruned)
-- `⊠` Locked worktree (protected from auto-removal)
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main OR `_` no commits).
+Include CI status and conflict detection:
-### JSON Output
+```bash
+wt list --full
+```
-Use `--format=json` for structured data. Each object contains two status maps
-with the same fields in the same order as Status Symbols above:
+Include branches that don't have worktrees:
-**`status`** - variant names for querying:
+```bash
+wt list --branches
+```
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
-- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
-- `git_operation`: `""` | `"Rebase"` | `"Merge"`
-- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
-- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
-- `user_marker`: string (optional)
+Output as JSON for scripting:
+
+```bash
+wt list --format=json
+```
-**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+### Status Symbols
-Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
+The Status column shows a compact summary. Symbols appear in this order:
+
+| Symbol | Meaning |
+|--------|---------|
+| `+` | Staged files (ready to commit) |
+| `!` | Modified files (unstaged changes) |
+| `?` | Untracked files |
+| `✖` | Merge conflicts (fix before continuing) |
+| `⊘` | Would conflict if merged to main |
+| `≡` | Matches main (identical contents) |
+| `_` | No commits (empty branch) |
+| `↻` | Rebase in progress |
+| `⋈` | Merge in progress |
+| `↑` | Ahead of main |
+| `↓` | Behind main |
+| `↕` | Diverged from main |
+| `⇡` | Ahead of remote |
+| `⇣` | Behind remote |
+| `⇅` | Diverged from remote |
+| `⎇` | Branch without worktree |
+| `⌫` | Prunable (directory missing) |
+| `⊠` | Locked worktree |
+
+Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
-**Worktree position fields** (for identifying special worktrees):
+### Columns
-- `is_main`: boolean - is the main worktree
-- `is_current`: boolean - is the current working directory (present when true)
-- `is_previous`: boolean - is the previous worktree from `wt switch` (present when true)
+| Column | Description |
+|--------|-------------|
+| **Branch** | Branch name |
+| **Status** | Compact symbols (see above) |
+| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
+| **main↕** | Commits ahead↑/behind↓ relative to main |
+| **main…±** | Line diffs in commits ahead of main (`--full` only) |
+| **Path** | Worktree directory |
+| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
+| **CI** | Pipeline status (`--full` only) |
+| **Commit** | Short hash (8 chars) |
+| **Age** | Time since last commit |
+| **Message** | Last commit message (truncated) |
+
+#### CI Status
+
+The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+
+- `●` green — All checks passed
+- `●` blue — Checks running
+- `●` red — Checks failed
+- `●` yellow — Merge conflicts with base
+- `●` gray — No checks configured
+- blank — No PR/MR found
+- dimmed — Stale (unpushed local changes)
-**Query examples:**
+### JSON Output
+
+The `--format=json` flag outputs structured data for scripting:
```bash
# Find worktrees with conflicts
-jq '.[] | select(.status.branch_state == "Conflicts")'
+wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with untracked files
-jq '.[] | select(.status.working_tree.untracked)'
+# Find worktrees with uncommitted changes
+wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Find worktrees in rebase or merge
-jq '.[] | select(.status.git_operation != "")'
+# Get current worktree
+wt list --format=json | jq '.[] | select(.is_current == true)'
-# Get branches ahead of main
-jq '.[] | select(.status.main_divergence == "Ahead")'
+# Find branches ahead of main
+wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
+```
-# Find locked worktrees
-jq '.[] | select(.locked != null)'
+**Status fields:**
-# Get current worktree info (useful for statusline tools)
-jq '.[] | select(.is_current == true)'
-```
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
+- `git_operation`: `""` | `"Rebase"` | `"Merge"`
+- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+
+**Position fields:**
+
+- `is_main`: boolean — is the main worktree
+- `is_current`: boolean — is the current directory
+- `is_previous`: boolean — is the previous worktree from `wt switch`
<!-- END AUTO-GENERATED -->
@@ -1047,71 +1007,67 @@ Global Options:
-v, --verbose
Show commands and debug info
-```
+Manages configuration, shell integration, and runtime settings. The command provides subcommands for setup, inspection, and cache management.
-### Setup Guide
+```
-1. Set up shell integration
+### Examples
- ```bash
- wt config shell install
- ```
+Install shell integration (required for directory switching):
- Or manually add to the shell config:
+```bash
+wt config shell install
+```
- ```bash
- eval "$(wt config shell init bash)"
- ```
+Create user config file with documented examples:
-2. (Optional) Create user config file
+```bash
+wt config create
+```
- ```bash
- wt config create
- ```
+Show current configuration and file locations:
- This creates `~/.config/worktrunk/config.toml` with examples.
+```bash
+wt config show
+```
-3. (Optional) Enable LLM commit messages
+### Shell Integration
- Install: `uv tool install -U llm`
- Configure: `llm keys set anthropic`
- Add to user config:
+Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
- ```toml
- [commit-generation]
- command = "llm"
- ```
+The `wt config shell install` command adds integration to the shell's config file. Manual installation:
-### LLM Setup Details
+```bash
+# For bash: add to ~/.bashrc
+eval "$(wt config shell init bash)"
-For Claude:
+# For zsh: add to ~/.zshrc
+eval "$(wt config shell init zsh)"
-```bash
-llm install llm-anthropic
-llm keys set anthropic
-llm models default claude-haiku-4-5-20251001
+# For fish: add to ~/.config/fish/config.fish
+wt config shell init fish | source
```
-For OpenAI:
+### Configuration Files
+
+**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
-```bash
-llm keys set openai
-```
+Personal settings like LLM commit generation, path templates, and default behaviors. The `wt config create` command generates a file with documented examples.
-Use `wt config show` to view the current configuration.
-Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
+**Project config** — `.config/wt.toml` in repository root:
-### Configuration Files
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
-**User config**:
+### LLM Commit Messages
-- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
-- Run `wt config create --help` to view documented examples
+Worktrunk can generate commit messages using an LLM. Enable in user config:
-**Project config**:
+```toml
+[commit-generation]
+command = "llm"
+```
-- Location: `.config/wt.toml` in repository root
-- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
<!-- END AUTO-GENERATED -->
@@ -1138,14 +1094,82 @@ Commands:
post-merge Run post-merge hook
Options:
- -h, --help Print help
+ -h, --help
+ Print help (see a summary with '-h')
Global Options:
- -C <path> Working directory for this command
- --config <path> User config file path
- -v, --verbose Show commands and debug info
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+
```
+### Examples
+
+Commit with an LLM-generated message:
+
+```bash
+wt step commit
+```
+
+Squash all branch commits into one:
+
+```bash
+wt step squash
+```
+
+Run pre-merge hooks (tests, lints):
+
+```bash
+wt step pre-merge
+```
+
+Rebase onto main:
+
+```bash
+wt step rebase
+```
+
+### Use Cases
+
+**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+
+```bash
+wt step commit
+wt step squash
+# manual review here
+wt step rebase
+wt step pre-merge
+wt step push
+```
+
+**CI integration** — Run hooks explicitly in CI environments:
+
+```bash
+wt step pre-merge --force # skip approval prompts
+```
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
+| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
+| `rebase` | Rebases the branch onto the target (default: main) |
+| `push` | Pushes changes to the local target branch |
+| `post-create` | Runs post-create hooks |
+| `post-start` | Runs post-start hooks |
+| `pre-commit` | Runs pre-commit hooks |
+| `pre-merge` | Runs pre-merge hooks |
+| `post-merge` | Runs post-merge hooks |
+
<!-- END AUTO-GENERATED -->
</details>
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 1f9428e5d..f5367c1d9 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -117,16 +117,12 @@ The output combines:
- **Conceptual content** - Edit the `after_long_help` attribute on the command
- **Usage/options/examples** - Edit the clap attributes (`about`, `long_about`, doc comments on args)
-After editing, regenerate the affected page(s):
+After editing, run the sync test (which auto-updates out-of-sync pages):
```bash
-wt switch --help-page > docs/content/switch.md
-wt merge --help-page > docs/content/merge.md
-# etc.
+cargo test --test integration test_command_pages_are_in_sync
```
-**Note:** Unlike inline `--help-md` snippets (which are auto-synced by `readme_sync.rs`), command pages require manual regeneration. There's no test that verifies they're in sync.
-
The generated files contain this warning comment:
```html
<!-- ⚠️ AUTO-GENERATED from `wt <command> --help-page` — edit cli.rs to update -->
diff --git a/docs/content/config.md b/docs/content/config.md
index ea3f94eac..ac596b9bd 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -6,69 +6,65 @@ weight = 15
group = "Commands"
+++
-## Setup Guide
+Manages configuration, shell integration, and runtime settings. The command provides subcommands for setup, inspection, and cache management.
-1. Set up shell integration
+## Examples
- ```bash
- wt config shell install
- ```
+Install shell integration (required for directory switching):
- Or manually add to the shell config:
+```bash
+wt config shell install
+```
- ```bash
- eval "$(wt config shell init bash)"
- ```
+Create user config file with documented examples:
-2. (Optional) Create user config file
+```bash
+wt config create
+```
- ```bash
- wt config create
- ```
+Show current configuration and file locations:
- This creates `~/.config/worktrunk/config.toml` with examples.
+```bash
+wt config show
+```
-3. (Optional) Enable LLM commit messages
+## Shell Integration
- Install: `uv tool install -U llm`
- Configure: `llm keys set anthropic`
- Add to user config:
+Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
- ```toml
- [commit-generation]
- command = "llm"
- ```
+The `wt config shell install` command adds integration to the shell's config file. Manual installation:
-## LLM Setup Details
+```bash
+# For bash: add to ~/.bashrc
+eval "$(wt config shell init bash)"
-For Claude:
+# For zsh: add to ~/.zshrc
+eval "$(wt config shell init zsh)"
-```bash
-llm install llm-anthropic
-llm keys set anthropic
-llm models default claude-haiku-4-5-20251001
+# For fish: add to ~/.config/fish/config.fish
+wt config shell init fish | source
```
-For OpenAI:
+## Configuration Files
-```bash
-llm keys set openai
-```
+**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
-Use `wt config show` to view the current configuration.
-Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
+Personal settings like LLM commit generation, path templates, and default behaviors. The `wt config create` command generates a file with documented examples.
-## Configuration Files
+**Project config** — `.config/wt.toml` in repository root:
+
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
-**User config**:
+## LLM Commit Messages
-- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
-- Run `wt config create --help` to view documented examples
+Worktrunk can generate commit messages using an LLM. Enable in user config:
-**Project config**:
+```toml
+[commit-generation]
+command = "llm"
+```
-- Location: `.config/wt.toml` in repository root
-- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
---
diff --git a/docs/content/list.md b/docs/content/list.md
index 9586f611a..7a974c8af 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -6,97 +6,120 @@ weight = 11
group = "Commands"
+++
-## Columns
+Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
-- **Branch:** Branch name
-- **Status:** Quick status symbols (see Status Symbols below)
-- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
-- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
-- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)
-- **Path:** Worktree directory location
-- **Remote⇅:** Commits ahead⇡/behind⇣ relative to tracking branch (e.g. `origin/branch`)
-- **CI** (`--full`): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
- - `●` **passed** (green) - All checks passed
- - `●` **running** (blue) - Checks in progress
- - `●` **failed** (red) - Checks failed
- - `●` **conflicts** (yellow) - Merge conflicts with base
- - `●` **no-ci** (gray) - PR/MR or workflow found but no checks configured
- - **(blank)** - No PR/MR or workflow found, or `gh`/`glab` CLI unavailable
- - **(dimmed)** - Stale: unpushed local changes differ from PR/MR head
-- **Commit:** Short commit hash (8 chars)
-- **Age:** Time since last commit (relative)
-- **Message:** Last commit message (truncated)
+## Examples
-## Status Symbols
+List all worktrees:
-Order: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
-
-- `+` Staged files (ready to commit)
-- `!` Modified files (unstaged changes)
-- `?` Untracked files present
-- `✖` **Merge conflicts** - unresolved conflicts in working tree (fix before continuing)
-- `⊘` **Would conflict** - merging into main would fail
-- `≡` Working tree matches main (identical contents, regardless of commit history)
-- `_` No commits (no commits ahead AND no uncommitted changes)
-- `↻` Rebase in progress
-- `⋈` Merge in progress
-- `↑` Ahead of main branch
-- `↓` Behind main branch
-- `↕` Diverged (both ahead and behind main)
-- `⇡` Ahead of remote tracking branch
-- `⇣` Behind remote tracking branch
-- `⇅` Diverged (both ahead and behind remote)
-- `⎇` Branch indicator (shown for branches without worktrees)
-- `⌫` Prunable worktree (directory missing, can be pruned)
-- `⊠` Locked worktree (protected from auto-removal)
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main OR `_` no commits).
+```bash
+wt list
+```
-## JSON Output
+Include CI status and conflict detection:
-Use `--format=json` for structured data. Each object contains two status maps
-with the same fields in the same order as Status Symbols above:
+```bash
+wt list --full
+```
-**`status`** - variant names for querying:
+Include branches that don't have worktrees:
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
-- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
-- `git_operation`: `""` | `"Rebase"` | `"Merge"`
-- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
-- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
-- `user_marker`: string (optional)
+```bash
+wt list --branches
+```
-**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+Output as JSON for scripting:
-Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
+```bash
+wt list --format=json
+```
-**Worktree position fields** (for identifying special worktrees):
+## Status Symbols
+
+The Status column shows a compact summary. Symbols appear in this order:
+
+| Symbol | Meaning |
+|--------|---------|
+| `+` | Staged files (ready to commit) |
+| `!` | Modified files (unstaged changes) |
+| `?` | Untracked files |
+| `✖` | Merge conflicts (fix before continuing) |
+| `⊘` | Would conflict if merged to main |
+| `≡` | Matches main (identical contents) |
+| `_` | No commits (empty branch) |
+| `↻` | Rebase in progress |
+| `⋈` | Merge in progress |
+| `↑` | Ahead of main |
+| `↓` | Behind main |
+| `↕` | Diverged from main |
+| `⇡` | Ahead of remote |
+| `⇣` | Behind remote |
+| `⇅` | Diverged from remote |
+| `⎇` | Branch without worktree |
+| `⌫` | Prunable (directory missing) |
+| `⊠` | Locked worktree |
+
+Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
+
+## Columns
-- `is_main`: boolean - is the main worktree
-- `is_current`: boolean - is the current working directory (present when true)
-- `is_previous`: boolean - is the previous worktree from `wt switch` (present when true)
+| Column | Description |
+|--------|-------------|
+| **Branch** | Branch name |
+| **Status** | Compact symbols (see above) |
+| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
+| **main↕** | Commits ahead↑/behind↓ relative to main |
+| **main…±** | Line diffs in commits ahead of main (`--full` only) |
+| **Path** | Worktree directory |
+| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
+| **CI** | Pipeline status (`--full` only) |
+| **Commit** | Short hash (8 chars) |
+| **Age** | Time since last commit |
+| **Message** | Last commit message (truncated) |
+
+### CI Status
+
+The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+
+- `●` green — All checks passed
+- `●` blue — Checks running
+- `●` red — Checks failed
+- `●` yellow — Merge conflicts with base
+- `●` gray — No checks configured
+- blank — No PR/MR found
+- dimmed — Stale (unpushed local changes)
-**Query examples:**
+## JSON Output
+
+The `--format=json` flag outputs structured data for scripting:
```bash
# Find worktrees with conflicts
-jq '.[] | select(.status.branch_state == "Conflicts")'
+wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with untracked files
-jq '.[] | select(.status.working_tree.untracked)'
+# Find worktrees with uncommitted changes
+wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Find worktrees in rebase or merge
-jq '.[] | select(.status.git_operation != "")'
+# Get current worktree
+wt list --format=json | jq '.[] | select(.is_current == true)'
-# Get branches ahead of main
-jq '.[] | select(.status.main_divergence == "Ahead")'
+# Find branches ahead of main
+wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
+```
-# Find locked worktrees
-jq '.[] | select(.locked != null)'
+**Status fields:**
-# Get current worktree info (useful for statusline tools)
-jq '.[] | select(.is_current == true)'
-```
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
+- `git_operation`: `""` | `"Rebase"` | `"Merge"`
+- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+
+**Position fields:**
+
+- `is_main`: boolean — is the main worktree
+- `is_current`: boolean — is the current directory
+- `is_previous`: boolean — is the previous worktree from `wt switch`
---
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 1c485dc24..684f3861c 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -6,68 +6,60 @@ weight = 12
group = "Commands"
+++
-## Operation
+Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
-Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-
-### Commit
-
-Uncommitted changes are staged and committed with LLM commit message.
-Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
+## Examples
-### Squash
+Merge current worktree into main:
-Multiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.
-Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
+```bash
+wt merge
+```
-### Rebase
+Keep the worktree after merging:
-Branch is rebased onto target. Conflicts abort the merge immediately.
+```bash
+wt merge --no-remove
+```
-### Hooks
+Preserve commit history (no squash):
-Pre-merge commands run after rebase (failures abort). Post-merge commands
-run after cleanup (failures logged). Skip all with `--no-verify`.
+```bash
+wt merge --no-squash
+```
-### Push
+Skip hooks and approval prompts:
-Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+```bash
+wt merge --no-verify --force
+```
-### Cleanup
+## The Pipeline
-Worktree and branch are removed. Skip with `--no-remove`.
+`wt merge` runs these steps in order:
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
-**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`.
+2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-## Examples
+3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
-Basic merge to main:
+4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
-```bash
-wt merge
-```
+5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
-Merge without squashing:
+6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
-```bash
-wt merge --no-squash
-```
+7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
-Keep worktree after merging:
+## Hooks
-```bash
-wt merge --no-remove
-```
+When merging, hooks run in this order:
-Skip all hooks:
+1. **pre-merge** — After rebase, before push. Failures abort the merge.
+2. **post-merge** — After cleanup. Failures are logged but don't abort.
-```bash
-wt merge --no-verify
-```
+The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
---
diff --git a/docs/content/remove.md b/docs/content/remove.md
index a2d83a20d..e5c84529b 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -6,64 +6,7 @@ weight = 13
group = "Commands"
+++
-## Operation
-
-Removes worktree directory, git metadata, and branch. Requires clean working tree.
-
-### No arguments (remove current)
-
-- Removes current worktree and switches to main worktree
-- In main worktree: switches to default branch
-
-### By name (remove specific)
-
-- Removes specified worktree(s) and branches
-- Current worktree removed last (switches to main first)
-
-### Worktree resolution
-
-Arguments are resolved to worktrees 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
-
-**Conflict detection**: If path `repo.foo/` has a worktree on branch `bar`, but
-branch `foo` has a different worktree at `repo.bar/`, an error is raised.
-
-**Special arguments**:
-
-- `@` - current worktree (by path, works in detached HEAD)
-- `-` - previous worktree (from switch history)
-- `^` - main worktree
-
-### Branch deletion
-
-By default, branches are deleted only when their content is already in the target branch:
-
-- no changes beyond the common ancestor — `git diff --name-only target...branch` is empty:
- no files changed between the merge base of `target`/`branch` and the tip of `branch`.
-- same content as target — `git rev-parse branch^{tree}` equals `git rev-parse target^{tree}`:
- both branches point at the same tracked-files snapshot (tree), even if the commits differ.
-
-This handles workflows where PRs are squash-merged or rebased, which don't preserve
-commit ancestry but do integrate the content. Use `-D` to delete unintegrated
-branches, or `--no-delete-branch` to always keep branches.
-
-### Background removal (default)
-
-- Returns immediately for continued work
-- Logs: `.git/wt-logs/{branch}-remove.log`
-- Use `--no-background` for foreground (blocking)
-
-### Cleanup
-
-Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
+Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
## Examples
@@ -73,13 +16,13 @@ Remove current worktree and branch:
wt remove
```
-Remove specific worktree and branch:
+Remove a specific worktree:
```bash
wt remove feature-branch
```
-Remove worktree but keep branch:
+Keep the branch after removing the worktree:
```bash
wt remove --no-delete-branch feature-branch
@@ -91,17 +34,38 @@ Remove multiple worktrees:
wt remove old-feature another-branch
```
-Remove in foreground (blocking):
+Force-delete an unmerged branch:
```bash
-wt remove --no-background feature-branch
+wt remove -D experimental
```
-Switch to default in main:
+## Branch Deletion
-```bash
-wt remove # (when already in main worktree)
-```
+By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+
+The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+
+## Background Removal
+
+Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+
+The `--no-background` flag runs removal in the foreground (blocking).
+
+## 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
+- `wt remove bar` also works (falls back to branch lookup)
+
+**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
---
diff --git a/docs/content/select.md b/docs/content/select.md
index 9b83bbd5f..dd62c9b5e 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -6,7 +6,36 @@ weight = 14
group = "Commands"
+++
+Interactive worktree picker with live preview. The selector shows worktree state at a glance — diff stats, commit history, and working tree status — without switching directories first.
+## Examples
+
+Open the interactive selector:
+
+```bash
+wt select
+```
+
+## The Interface
+
+The selector displays a two-panel layout: a worktree list on the left and a preview panel on the right. The preview updates automatically when navigating between worktrees.
+
+**Preview tabs** — toggled with number keys:
+
+1. **Diff** — Changes relative to main branch
+2. **Log** — Recent commits on the branch
+3. **Status** — Working tree status (staged, modified, untracked)
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` or `j`/`k` | Navigate worktree list |
+| `Enter` | Switch to selected worktree |
+| `Esc` or `q` | Cancel |
+| `/` | Filter worktrees |
+| `1`/`2`/`3` | Switch preview tab |
+| `Alt+p` | Toggle preview panel |
---
diff --git a/docs/content/step.md b/docs/content/step.md
index 8a8ff97f5..e525e86ed 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -6,7 +6,66 @@ weight = 16
group = "Commands"
+++
+Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+## Examples
+
+Commit with an LLM-generated message:
+
+```bash
+wt step commit
+```
+
+Squash all branch commits into one:
+
+```bash
+wt step squash
+```
+
+Run pre-merge hooks (tests, lints):
+
+```bash
+wt step pre-merge
+```
+
+Rebase onto main:
+
+```bash
+wt step rebase
+```
+
+## Use Cases
+
+**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+
+```bash
+wt step commit
+wt step squash
+# manual review here
+wt step rebase
+wt step pre-merge
+wt step push
+```
+
+**CI integration** — Run hooks explicitly in CI environments:
+
+```bash
+wt step pre-merge --force # skip approval prompts
+```
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
+| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
+| `rebase` | Rebases the branch onto the target (default: main) |
+| `push` | Pushes changes to the local target branch |
+| `post-create` | Runs post-create hooks |
+| `post-start` | Runs post-start hooks |
+| `pre-commit` | Runs pre-commit hooks |
+| `pre-merge` | Runs pre-merge hooks |
+| `post-merge` | Runs post-merge hooks |
---
@@ -30,10 +89,16 @@ Commands:
post-merge Run post-merge hook
Options:
- -h, --help Print help
+ -h, --help
+ Print help (see a summary with '-h')
Global Options:
- -C <path> Working directory for this command
- --config <path> User config file path
- -v, --verbose Show commands and debug info
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
```
diff --git a/src/cli.rs b/src/cli.rs
index 0d615da31..da2e7520b 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -654,69 +654,65 @@ pub enum Commands {
/// Manage configuration and shell integration
#[command(
about = "Manage configuration and shell integration",
- after_long_help = r#"## Setup Guide
+ after_long_help = r#"Manages configuration, shell integration, and runtime settings. The command provides subcommands for setup, inspection, and cache management.
-1. Set up shell integration
+## Examples
- ```console
- wt config shell install
- ```
+Install shell integration (required for directory switching):
- Or manually add to the shell config:
+```console
+wt config shell install
+```
- ```console
- eval "$(wt config shell init bash)"
- ```
+Create user config file with documented examples:
-2. (Optional) Create user config file
+```console
+wt config create
+```
- ```console
- wt config create
- ```
+Show current configuration and file locations:
- This creates `~/.config/worktrunk/config.toml` with examples.
+```console
+wt config show
+```
-3. (Optional) Enable LLM commit messages
+## Shell Integration
- Install: `uv tool install -U llm`
- Configure: `llm keys set anthropic`
- Add to user config:
+Shell integration allows Worktrunk to change the shell's working directory after `wt switch`. Without it, commands run in a subprocess and directory changes don't persist.
- ```toml
- [commit-generation]
- command = "llm"
- ```
+The `wt config shell install` command adds integration to the shell's config file. Manual installation:
-## LLM Setup Details
+```console
+# For bash: add to ~/.bashrc
+eval "$(wt config shell init bash)"
-For Claude:
+# For zsh: add to ~/.zshrc
+eval "$(wt config shell init zsh)"
-```console
-llm install llm-anthropic
-llm keys set anthropic
-llm models default claude-haiku-4-5-20251001
+# For fish: add to ~/.config/fish/config.fish
+wt config shell init fish | source
```
-For OpenAI:
+## Configuration Files
+
+**User config** — `~/.config/worktrunk/config.toml` (or `$WORKTRUNK_CONFIG_PATH`):
-```console
-llm keys set openai
-```
+Personal settings like LLM commit generation, path templates, and default behaviors. The `wt config create` command generates a file with documented examples.
-Use `wt config show` to view the current configuration.
-Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
+**Project config** — `.config/wt.toml` in repository root:
-## Configuration Files
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
-**User config**:
+## LLM Commit Messages
-- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
-- Run `wt config create --help` to view documented examples
+Worktrunk can generate commit messages using an LLM. Enable in user config:
-**Project config**:
+```toml
+[commit-generation]
+command = "llm"
+```
-- Location: `.config/wt.toml` in repository root
-- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
"#
)]
Config {
@@ -725,7 +721,70 @@ Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
},
/// Workflow building blocks
- #[command(name = "step")]
+ #[command(
+ name = "step",
+ after_long_help = r#"Individual workflow steps for scripting and automation. Each subcommand performs one step of the `wt merge` pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+
+## Examples
+
+Commit with an LLM-generated message:
+
+```console
+wt step commit
+```
+
+Squash all branch commits into one:
+
+```console
+wt step squash
+```
+
+Run pre-merge hooks (tests, lints):
+
+```console
+wt step pre-merge
+```
+
+Rebase onto main:
+
+```console
+wt step rebase
+```
+
+## Use Cases
+
+**Custom merge workflow** — Run steps individually when `wt merge` doesn't fit, such as adding manual review between squash and rebase:
+
+```console
+wt step commit
+wt step squash
+# manual review here
+wt step rebase
+wt step pre-merge
+wt step push
+```
+
+**CI integration** — Run hooks explicitly in CI environments:
+
+```console
+wt step pre-merge --force # skip approval prompts
+```
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `commit` | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
+| `squash` | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
+| `rebase` | Rebases the branch onto the target (default: main) |
+| `push` | Pushes changes to the local target branch |
+| `post-create` | Runs post-create hooks |
+| `post-start` | Runs post-start hooks |
+| `pre-commit` | Runs pre-commit hooks |
+| `pre-merge` | Runs pre-merge hooks |
+| `post-merge` | Runs post-merge hooks |
+"#
+ )]
Step {
#[command(subcommand)]
action: StepCommand,
@@ -735,100 +794,159 @@ Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
///
/// Toggle preview tabs with 1/2/3 keys. Toggle preview visibility with alt-p.
#[cfg(unix)]
+ #[command(
+ after_long_help = r#"Interactive worktree picker with live preview. The selector shows worktree state at a glance — diff stats, commit history, and working tree status — without switching directories first.
+
+## Examples
+
+Open the interactive selector:
+
+```console
+wt select
+```
+
+## The Interface
+
+The selector displays a two-panel layout: a worktree list on the left and a preview panel on the right. The preview updates automatically when navigating between worktrees.
+
+**Preview tabs** — toggled with number keys:
+
+1. **Diff** — Changes relative to main branch
+2. **Log** — Recent commits on the branch
+3. **Status** — Working tree status (staged, modified, untracked)
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `↑`/`↓` or `j`/`k` | Navigate worktree list |
+| `Enter` | Switch to selected worktree |
+| `Esc` or `q` | Cancel |
+| `/` | Filter worktrees |
+| `1`/`2`/`3` | Switch preview tab |
+| `Alt+p` | Toggle preview panel |
+"#
+ )]
Select,
/// List worktrees and optionally branches
- #[command(after_long_help = "## Columns
-
-- **Branch:** Branch name
-- **Status:** Quick status symbols (see Status Symbols below)
-- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
-- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
-- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)
-- **Path:** Worktree directory location
-- **Remote⇅:** Commits ahead⇡/behind⇣ relative to tracking branch (e.g. `origin/branch`)
-- **CI** (`--full`): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
- - `●` **passed** (green) - All checks passed
- - `●` **running** (blue) - Checks in progress
- - `●` **failed** (red) - Checks failed
- - `●` **conflicts** (yellow) - Merge conflicts with base
- - `●` **no-ci** (gray) - PR/MR or workflow found but no checks configured
- - **(blank)** - No PR/MR or workflow found, or `gh`/`glab` CLI unavailable
- - **(dimmed)** - Stale: unpushed local changes differ from PR/MR head
-- **Commit:** Short commit hash (8 chars)
-- **Age:** Time since last commit (relative)
-- **Message:** Last commit message (truncated)
+ #[command(
+ after_long_help = r#"Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
-## Status Symbols
+## Examples
-Order: `+!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
-
-- `+` Staged files (ready to commit)
-- `!` Modified files (unstaged changes)
-- `?` Untracked files present
-- `✖` **Merge conflicts** - unresolved conflicts in working tree (fix before continuing)
-- `⊘` **Would conflict** - merging into main would fail
-- `≡` Working tree matches main (identical contents, regardless of commit history)
-- `_` No commits (no commits ahead AND no uncommitted changes)
-- `↻` Rebase in progress
-- `⋈` Merge in progress
-- `↑` Ahead of main branch
-- `↓` Behind main branch
-- `↕` Diverged (both ahead and behind main)
-- `⇡` Ahead of remote tracking branch
-- `⇣` Behind remote tracking branch
-- `⇅` Diverged (both ahead and behind remote)
-- `⎇` Branch indicator (shown for branches without worktrees)
-- `⌫` Prunable worktree (directory missing, can be pruned)
-- `⊠` Locked worktree (protected from auto-removal)
-
-Rows are dimmed when there's no marginal contribution (`≡` matches main OR `_` no commits).
+List all worktrees:
-## JSON Output
+```console
+wt list
+```
-Use `--format=json` for structured data. Each object contains two status maps
-with the same fields in the same order as Status Symbols above:
+Include CI status and conflict detection:
-**`status`** - variant names for querying:
+```console
+wt list --full
+```
-- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
-- `branch_state`: `\"\"` | `\"Conflicts\"` | `\"MergeTreeConflicts\"` | `\"MatchesMain\"` | `\"NoCommits\"`
-- `git_operation`: `\"\"` | `\"Rebase\"` | `\"Merge\"`
-- `main_divergence`: `\"\"` | `\"Ahead\"` | `\"Behind\"` | `\"Diverged\"`
-- `upstream_divergence`: `\"\"` | `\"Ahead\"` | `\"Behind\"` | `\"Diverged\"`
-- `user_marker`: string (optional)
+Include branches that don't have worktrees:
+
+```console
+wt list --branches
+```
-**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+Output as JSON for scripting:
-Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
+```console
+wt list --format=json
+```
-**Worktree position fields** (for identifying special worktrees):
+## Status Symbols
-- `is_main`: boolean - is the main worktree
-- `is_current`: boolean - is the current working directory (present when true)
-- `is_previous`: boolean - is the previous worktree from `wt switch` (present when true)
+The Status column shows a compact summary. Symbols appear in this order:
+
+| Symbol | Meaning |
+|--------|---------|
+| `+` | Staged files (ready to commit) |
+| `!` | Modified files (unstaged changes) |
+| `?` | Untracked files |
+| `✖` | Merge conflicts (fix before continuing) |
+| `⊘` | Would conflict if merged to main |
+| `≡` | Matches main (identical contents) |
+| `_` | No commits (empty branch) |
+| `↻` | Rebase in progress |
+| `⋈` | Merge in progress |
+| `↑` | Ahead of main |
+| `↓` | Behind main |
+| `↕` | Diverged from main |
+| `⇡` | Ahead of remote |
+| `⇣` | Behind remote |
+| `⇅` | Diverged from remote |
+| `⎇` | Branch without worktree |
+| `⌫` | Prunable (directory missing) |
+| `⊠` | Locked worktree |
+
+Rows are dimmed when there's no marginal contribution (`≡` matches main or `_` no commits).
+
+## Columns
+
+| Column | Description |
+|--------|-------------|
+| **Branch** | Branch name |
+| **Status** | Compact symbols (see above) |
+| **HEAD±** | Uncommitted changes: `+added` `-deleted` lines |
+| **main↕** | Commits ahead↑/behind↓ relative to main |
+| **main…±** | Line diffs in commits ahead of main (`--full` only) |
+| **Path** | Worktree directory |
+| **Remote⇅** | Commits ahead⇡/behind⇣ vs tracking branch |
+| **CI** | Pipeline status (`--full` only) |
+| **Commit** | Short hash (8 chars) |
+| **Age** | Time since last commit |
+| **Message** | Last commit message (truncated) |
+
+### CI Status
+
+The CI column (`--full`) shows pipeline status from GitHub/GitLab:
+
+- `●` green — All checks passed
+- `●` blue — Checks running
+- `●` red — Checks failed
+- `●` yellow — Merge conflicts with base
+- `●` gray — No checks configured
+- blank — No PR/MR found
+- dimmed — Stale (unpushed local changes)
-**Query examples:**
+## JSON Output
+
+The `--format=json` flag outputs structured data for scripting:
```console
# Find worktrees with conflicts
-jq '.[] | select(.status.branch_state == \"Conflicts\")'
+wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'
-# Find worktrees with untracked files
-jq '.[] | select(.status.working_tree.untracked)'
+# Find worktrees with uncommitted changes
+wt list --format=json | jq '.[] | select(.status.working_tree.modified)'
-# Find worktrees in rebase or merge
-jq '.[] | select(.status.git_operation != \"\")'
+# Get current worktree
+wt list --format=json | jq '.[] | select(.is_current == true)'
-# Get branches ahead of main
-jq '.[] | select(.status.main_divergence == \"Ahead\")'
+# Find branches ahead of main
+wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
+```
-# Find locked worktrees
-jq '.[] | select(.locked != null)'
+**Status fields:**
-# Get current worktree info (useful for statusline tools)
-jq '.[] | select(.is_current == true)'
-```")]
+- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
+- `branch_state`: `""` | `"Conflicts"` | `"MergeTreeConflicts"` | `"MatchesMain"` | `"NoCommits"`
+- `git_operation`: `""` | `"Rebase"` | `"Merge"`
+- `main_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+- `upstream_divergence`: `""` | `"Ahead"` | `"Behind"` | `"Diverged"`
+
+**Position fields:**
+
+- `is_main`: boolean — is the main worktree
+- `is_current`: boolean — is the current directory
+- `is_previous`: boolean — is the previous worktree from `wt switch`
+"#
+ )]
#[command(args_conflicts_with_subcommands = true)]
List {
#[command(subcommand)]
@@ -863,108 +981,92 @@ jq '.[] | select(.is_current == true)'
},
/// Switch to a worktree
- #[command(after_long_help = r#"## 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`.
+ #[command(
+ after_long_help = r#"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:
```console
-wt switch feature-branch
+wt switch feature-auth
```
-Create new worktree from main:
+Create a new worktree for a fresh branch:
```console
wt switch --create new-feature
```
-Switch to previous worktree:
+Create from a specific base branch:
```console
-wt switch -
+wt switch --create hotfix --base production
```
-Create from specific base:
+Switch to the previous worktree (like `cd -`):
```console
-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.
```console
-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
-```console
+# 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) |
```console
-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)
+"#
+ )]
Switch {
/// Branch or worktree name
///
@@ -996,64 +1098,8 @@ wt remove @ # Remove current worktree
},
/// Remove worktree and branch
- #[command(after_long_help = r#"## Operation
-
-Removes worktree directory, git metadata, and branch. Requires clean working tree.
-
-### No arguments (remove current)
-
-- Removes current worktree and switches to main worktree
-- In main worktree: switches to default branch
-
-### By name (remove specific)
-
-- Removes specified worktree(s) and branches
-- Current worktree removed last (switches to main first)
-
-### Worktree resolution
-
-Arguments are resolved to worktrees 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
-- `wt remove bar` also works (falls back to branch lookup)
-
-**Conflict detection**: If path `repo.foo/` has a worktree on branch `bar`, but
-branch `foo` has a different worktree at `repo.bar/`, an error is raised.
-
-**Special arguments**:
-
-- `@` - current worktree (by path, works in detached HEAD)
-- `-` - previous worktree (from switch history)
-- `^` - main worktree
-
-### Branch deletion
-
-By default, branches are deleted only when their content is already in the target branch:
-
-- no changes beyond the common ancestor — `git diff --name-only target...branch` is empty:
- no files changed between the merge base of `target`/`branch` and the tip of `branch`.
-- same content as target — `git rev-parse branch^{tree}` equals `git rev-parse target^{tree}`:
- both branches point at the same tracked-files snapshot (tree), even if the commits differ.
-
-This handles workflows where PRs are squash-merged or rebased, which don't preserve
-commit ancestry but do integrate the content. Use `-D` to delete unintegrated
-branches, or `--no-delete-branch` to always keep branches.
-
-### Background removal (default)
-
-- Returns immediately for continued work
-- Logs: `.git/wt-logs/{branch}-remove.log`
-- Use `--no-background` for foreground (blocking)
-
-### Cleanup
-
-Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (`core.fsmonitor=true`). No effect on Watchman users.
+ #[command(
+ after_long_help = r#"Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
## Examples
@@ -1063,13 +1109,13 @@ Remove current worktree and branch:
wt remove
```
-Remove specific worktree and branch:
+Remove a specific worktree:
```console
wt remove feature-branch
```
-Remove worktree but keep branch:
+Keep the branch after removing the worktree:
```console
wt remove --no-delete-branch feature-branch
@@ -1081,17 +1127,40 @@ Remove multiple worktrees:
wt remove old-feature another-branch
```
-Remove in foreground (blocking):
+Force-delete an unmerged branch:
```console
-wt remove --no-background feature-branch
+wt remove -D experimental
```
-Switch to default in main:
+## Branch Deletion
-```console
-wt remove # (when already in main worktree)
-```"#)]
+By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
+
+The `-D` flag overrides this safety check and force-deletes unmerged branches. The `--no-delete-branch` flag prevents branch deletion entirely.
+
+## Background Removal
+
+Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to `.git/wt-logs/{branch}-remove.log`.
+
+The `--no-background` flag runs removal in the foreground (blocking).
+
+## 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, use 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 remove foo` removes `repo.foo/` and the `bar` branch
+- `wt remove bar` also works (falls back to branch lookup)
+
+**Shortcuts**: `@` (current worktree), `-` (previous worktree), `^` (main worktree)
+"#
+ )]
Remove {
/// Worktree or branch (@ for current)
#[arg(add = crate::completion::worktree_branch_completer())]
@@ -1111,68 +1180,63 @@ wt remove # (when already in main worktree)
},
/// Merge worktree into target branch
- #[command(after_long_help = r#"## Operation
-
-Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-
-### Commit
+ #[command(
+ after_long_help = r#"Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
-Uncommitted changes are staged and committed with LLM commit message.
-Use `--stage=tracked` to stage only tracked files, or `--stage=none` to commit only what's already staged.
+## Examples
-### Squash
+Merge current worktree into main:
-Multiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.
-Skip with `--no-squash`. Safety backup: `git reflog show refs/wt-backup/<branch>`
+```console
+wt merge
+```
-### Rebase
+Keep the worktree after merging:
-Branch is rebased onto target. Conflicts abort the merge immediately.
+```console
+wt merge --no-remove
+```
-### Hooks
+Preserve commit history (no squash):
-Pre-merge commands run after rebase (failures abort). Post-merge commands
-run after cleanup (failures logged). Skip all with `--no-verify`.
+```console
+wt merge --no-squash
+```
-### Push
+Skip hooks and approval prompts:
-Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+```console
+wt merge --no-verify --force
+```
-### Cleanup
+## The Pipeline
-Worktree and branch are removed. Skip with `--no-remove`.
+`wt merge` runs these steps in order:
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+1. **Commit** — Stages and commits uncommitted changes with an LLM-generated message. The `--stage` flag controls what gets staged: `all` (default), `tracked`, or `none`.
-**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`.
+2. **Squash** — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The `--no-squash` flag preserves individual commits. A backup ref is saved to `refs/wt-backup/<branch>`.
-## Examples
+3. **Rebase** — Rebases onto the target branch. Conflicts abort the merge immediately.
-Basic merge to main:
+4. **Pre-merge hooks** — Project-defined commands run after rebase. Failures abort the merge.
-```console
-wt merge
-```
+5. **Push** — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
-Merge without squashing:
+6. **Cleanup** — Removes the worktree and branch. The `--no-remove` flag keeps the worktree.
-```console
-wt merge --no-squash
-```
+7. **Post-merge hooks** — Project-defined commands run after cleanup. Failures are logged but don't abort.
-Keep worktree after merging:
+## Hooks
-```console
-wt merge --no-remove
-```
+When merging, hooks run in this order:
-Skip all hooks:
+1. **pre-merge** — After rebase, before push. Failures abort the merge.
+2. **post-merge** — After cleanup. Failures are logged but don't abort.
-```console
-wt merge --no-verify
-```"#)]
+The `--no-verify` flag skips all hooks. See [Hooks](/hooks/) for configuration details.
+"#
+ )]
Merge {
/// Target branch
///
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 8e8d1eecf..98ebc415e 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -92,3 +92,45 @@ branch: Option<String>,
- `worktree_branch_completer()` - Completes with worktree paths and branch names
**Pattern:** All branch arguments should use `branch_value_completer()` for consistency with commands like `wt merge`, `wt switch --base`, `wt rebase`.
+
+## Command Documentation Guidelines
+
+When writing or updating command docs in `docs/content/`, follow this structure and these principles. Load the `documentation` skill for additional guidance.
+
+### Structure
+
+Each command page should follow this order:
+
+1. **Intro paragraph** — One or two sentences: what the command does and when to use it. Integrate key behavioral distinctions (e.g., "Switching to an existing worktree is just a directory change. With `--create`, hooks run.")
+2. **Examples** — Common use cases with brief labels, immediately after intro
+3. **Feature sections** — Deeper explanation of major features (e.g., "Creating Worktrees", "Shortcuts")
+4. **Hooks** — Brief summary with link to `/hooks/` for details
+5. **Technical details** — Implementation details like argument resolution, pushed to the bottom
+6. **Command Reference** — Auto-generated from `--help-page`, always last
+
+### Writing Style
+
+- **Indicative mood over imperative** — "The `--create` flag creates..." not "Use `--create` to create..."
+- **Spaced em-dashes** — "instant — no stashing" not "instant—no stashing"
+- **No second person** — Describe behavior, don't address the reader
+- **Concrete examples** — Real commands, actual output, specific scenarios
+- **Link to dedicated pages** — Don't duplicate content from `/hooks/`, `/configuration/`, etc.
+
+### What to Avoid
+
+- AI-slop: series of headings with 3-5 bullets each
+- Redundant content that duplicates other pages
+- Technical details at the top (push Operation/Resolution sections down)
+- Wrapper sections that just contain one subsection (remove "Operation" if it only contains "How Arguments Are Resolved")
+
+### Example: Good Intro
+
+```markdown
+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.
+```
+
+### Updating These Guidelines
+
+As command docs are improved, update this section to capture new patterns that emerge.
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index ae9a02f9f..fc6a24254 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -859,6 +859,77 @@ fn test_docs_quickstart_examples_are_in_sync() {
}
}
+/// Command pages generated via `wt <cmd> --help-page`
+const COMMAND_PAGES: &[&str] = &[
+ "switch", "list", "merge", "remove", "select", "config", "step",
+];
+
+#[test]
+fn test_command_pages_are_in_sync() {
+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ let mut errors = Vec::new();
+ let mut updated = 0;
+
+ for cmd in COMMAND_PAGES {
+ let doc_path = project_root.join(format!("docs/content/{}.md", cmd));
+ if !doc_path.exists() {
+ errors.push(format!("Missing command page: {}", doc_path.display()));
+ continue;
+ }
+
+ // Run wt <cmd> --help-page
+ let output = Command::new(env!("CARGO_BIN_EXE_wt"))
+ .args([cmd, "--help-page"])
+ .current_dir(project_root)
+ .output()
+ .expect("Failed to run wt --help-page");
+
+ if !output.status.success() {
+ errors.push(format!(
+ "'wt {} --help-page' failed (exit {}): {}",
+ cmd,
+ output.status.code().unwrap_or(-1),
+ String::from_utf8_lossy(&output.stderr)
+ ));
+ continue;
+ }
+
+ // Strip trailing whitespace from each line (pre-commit does this)
+ let expected: String = String::from_utf8_lossy(&output.stdout)
+ .lines()
+ .map(|line| line.trim_end())
+ .collect::<Vec<_>>()
+ .join("\n")
+ + "\n"; // Ensure trailing newline
+ if expected.trim().is_empty() {
+ errors.push(format!(
+ "Empty output from 'wt {} --help-page': {}",
+ cmd,
+ String::from_utf8_lossy(&output.stderr)
+ ));
+ continue;
+ }
+
+ let current = fs::read_to_string(&doc_path)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", doc_path.display(), e));
+
+ if current != expected {
+ fs::write(&doc_path, &expected)
+ .unwrap_or_else(|e| panic!("Failed to write {}: {}", doc_path.display(), e));
+ println!("Updated docs/content/{}.md", cmd);
+ updated += 1;
+ }
+ }
+
+ if updated > 0 {
+ println!("Updated {} command page(s)", updated);
+ }
+
+ if !errors.is_empty() {
+ panic!("Command pages out of sync:\n\n{}\n", errors.join("\n"));
+ }
+}
+
/// Strip HTML tags from a string (simple implementation for command extraction)
fn strip_html_tags(s: &str) -> String {
let mut result = String::new();
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 3a4b992e7..8419b7837 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -42,54 +42,52 @@ Usage: wt config [OPTIONS] <COMMAND>
-v, --verbose
Show commands and debug info
-Setup Guide
+Manages configuration, shell integration, and runtime settings. The command provides subcommands for setup, inspection, and cache management.
-1. Set up shell integration
+Examples
-  wt config shell install
+Install shell integration (required for directory switching):
- Or manually add to the shell config:
+ wt config shell install
-  eval "$(wt config shell init bash)"
+Create user config file with documented examples:
-2. (Optional) Create user config file
+ wt config create
-  wt config create
+Show current configuration and file locations:
- This creates ~/.config/worktrunk/config.toml with examples.
+ wt config show
-3. (Optional) Enable LLM commit messages
+Shell Integration
- Install: uv tool install -U llm
- Configure: llm keys set anthropic
- Add to user config:
+Shell integration allows Worktrunk to change the shell's working directory after wt switch. Without it, commands run in a subprocess and directory changes don't persist.
-  [commit-generation]
-  command = "llm"
+The wt config shell install command adds integration to the shell's config file. Manual installation:
-LLM Setup Details
+ # For bash: add to ~/.bashrc
+ eval "$(wt config shell init bash)"
+ 
+ # For zsh: add to ~/.zshrc
+ eval "$(wt config shell init zsh)"
+ 
+ # For fish: add to ~/.config/fish/config.fish
+ wt config shell init fish | source
-For Claude:
-
- llm install llm-anthropic
- llm keys set anthropic
- llm models default claude-haiku-4-5-20251001
+Configuration Files
-For OpenAI:
+User config — ~/.config/worktrunk/config.toml (or $WORKTRUNK_CONFIG_PATH):
- llm keys set openai
+Personal settings like LLM commit generation, path templates, and default behaviors. The wt config create command generates a file with documented examples.
-Use wt config show to view the current configuration.
-Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
+Project config — .config/wt.toml in repository root:
-Configuration Files
+Project-specific hooks: post-create, post-start, pre-commit, pre-merge, post-merge. See [Hooks](/hooks/) for details.
-User config:
+LLM Commit Messages
-- Location: ~/.config/worktrunk/config.toml (or WORKTRUNK_CONFIG_PATH)
-- Run wt config create --help to view documented examples
+Worktrunk can generate commit messages using an LLM. Enable in user config:
-Project config:
+ [commit-generation]
+ command = "llm"
-- Location: .config/wt.toml in repository root
-- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+See [LLM Commits](/llm-commits/) for installation, provider setup, and customization.
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 84f05a540..2b1fb731a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -57,92 +57,107 @@ Usage: wt list [OPTIONS]
-v, --verbose
Show commands and debug info
-Columns
+Show all worktrees with their status at a glance. The table includes uncommitted changes, divergence from main and remote, and optional CI status.
-- Branch: Branch name
-- Status: Quick status symbols (see Status Symbols below)
-- HEAD±: Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
-- main↕: Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
-- main…± (--full): Line diffs in commits ahead of main (+added -deleted)
-- Path: Worktree directory location
-- Remote⇅: Commits ahead⇡/behind⇣ relative to tracking branch (e.g. origin/branch)
-- CI (--full): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
- - ● passed (green) - All checks passed
- - ● running (blue) - Checks in progress
- - ● failed (red) - Checks failed
- - ● conflicts (yellow) - Merge conflicts with base
- - ● no-ci (gray) - PR/MR or workflow found but no checks configured
- - (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable
- - (dimmed) - Stale: unpushed local changes differ from PR/MR head
-- Commit: Short commit hash (8 chars)
-- Age: Time since last commit (relative)
-- Message: Last commit message (truncated)
+Examples
-Status Symbols
+List all worktrees:
-Order: +!? ✖⚠≡_ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠
-
-- + Staged files (ready to commit)
-- ! Modified files (unstaged changes)
-- ? Untracked files present
-- ✖ Merge conflicts - unresolved conflicts in working tree (fix before continuing)
-- ⊘ Would conflict - merging into main would fail
-- ≡ Working tree matches main (identical contents, regardless of commit history)
-- _ No commits (no commits ahead AND no uncommitted changes)
-- ↻ Rebase in progress
-- ⋈ Merge in progress
-- ↑ Ahead of main branch
-- ↓ Behind main branch
-- ↕ Diverged (both ahead and behind main)
-- ⇡ Ahead of remote tracking branch
-- ⇣ Behind remote tracking branch
-- ⇅ Diverged (both ahead and behind remote)
-- ⎇ Branch indicator (shown for branches without worktrees)
-- ⌫ Prunable worktree (directory missing, can be pruned)
-- ⊠ Locked worktree (protected from auto-removal)
-
-Rows are dimmed when there's no marginal contribution (≡ matches main OR _ no commits).
+ wt list
-JSON Output
+Include CI status and conflict detection:
-Use --format=json for structured data. Each object contains two status maps
-with the same fields in the same order as Status Symbols above:
+ wt list --full
-`status` - variant names for querying:
+Include branches that don't have worktrees:
-- working_tree: {untracked, modified, staged, renamed, deleted} booleans
-- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
-- git_operation: "" | "Rebase" | "Merge"
-- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
-- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
-- user_marker: string (optional)
+ wt list --branches
+
+Output as JSON for scripting:
+
+ wt list --format=json
-`status_symbols` - Unicode symbols for display (same fields, plus worktree_attrs: ⎇/⌫/⊠)
+Status Symbols
-Note: locked and prunable are top-level fields on worktree objects, not in status.
+The Status column shows a compact summary. Symbols appear in this order:
+
+| Symbol | Meaning |
+|--------|---------|
+| + | Staged files (ready to commit) |
+| ! | Modified files (unstaged changes) |
+| ? | Untracked files |
+| ✖ | Merge conflicts (fix before continuing) |
+| ⊘ | Would conflict if merged to main |
+| ≡ | Matches main (identical contents) |
+| _ | No commits (empty branch) |
+| ↻ | Rebase in progress |
+| ⋈ | Merge in progress |
+| ↑ | Ahead of main |
+| ↓ | Behind main |
+| ↕ | Diverged from main |
+| ⇡ | Ahead of remote |
+| ⇣ | Behind remote |
+| ⇅ | Diverged from remote |
+| ⎇ | Branch without worktree |
+| ⌫ | Prunable (directory missing) |
+| ⊠ | Locked worktree |
+
+Rows are dimmed when there's no marginal contribution (≡ matches main or _ no commits).
-Worktree position fields (for identifying special worktrees):
+Columns
-- is_main: boolean - is the main worktree
-- is_current: boolean - is the current working directory (present when true)
-- is_previous: boolean - is the previous worktree from wt switch (present when true)
+| Column | Description |
+|--------|-------------|
+| Branch | Branch name |
+| Status | Compact symbols (see above) |
+| HEAD± | Uncommitted changes: +added -deleted lines |
+| main↕ | Commits ahead↑/behind↓ relative to main |
+| main…± | Line diffs in commits ahead of main (--full only) |
+| Path | Worktree directory |
+| Remote⇅ | Commits ahead⇡/behind⇣ vs tracking branch |
+| CI | Pipeline status (--full only) |
+| Commit | Short hash (8 chars) |
+| Age | Time since last commit |
+| Message | Last commit message (truncated) |
+
+CI Status
+
+The CI column (--full) shows pipeline status from GitHub/GitLab:
+
+- ● green — All checks passed
+- ● blue — Checks running
+- ● red — Checks failed
+- ● yellow — Merge conflicts with base
+- ● gray — No checks configured
+- blank — No PR/MR found
+- dimmed — Stale (unpushed local changes)
-Query examples:
+JSON Output
+
+The --format=json flag outputs structured data for scripting:
# Find worktrees with conflicts
- jq '.[] | select(.status.branch_state == "Conflicts")'
- 
- # Find worktrees with untracked files
- jq '.[] | select(.status.working_tree.untracked)'
- 
- # Find worktrees in rebase or merge
- jq '.[] | select(.status.git_operation != "")'
+ wt list --format=json | jq '.[] | select(.status.branch_state == "Conflicts")'

- # Get branches ahead of main
- jq '.[] | select(.status.main_divergence == "Ahead")'
+ # Find worktrees with uncommitted changes
+ wt list --format=json | jq '.[] | select(.status.working_tree.modified)'

- # Find locked worktrees
- jq '.[] | select(.locked != null)'
+ # Get current worktree
+ wt list --format=json | jq '.[] | select(.is_current == true)'

- # Get current worktree info (useful for statusline tools)
- jq '.[] | select(.is_current == true)'
+ # Find branches ahead of main
+ wt list --format=json | jq '.[] | select(.status.main_divergence == "Ahead")'
+
+Status fields:
+
+- working_tree: {untracked, modified, staged, renamed, deleted} booleans
+- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
+- git_operation: "" | "Rebase" | "Merge"
+- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
+- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
+
+Position fields:
+
+- is_main: boolean — is the main worktree
+- is_current: boolean — is the current directory
+- is_previous: boolean — is the previous worktree from wt switch
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 6a30bd1d3..722fb48d4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -63,57 +63,49 @@ Usage: wt merge [OPTIONS] [TARGET]
-v, --verbose
Show commands and debug info
-Operation
+Integrates the current branch into the target branch (default: main) and removes the worktree. All steps — commit, squash, rebase, push, cleanup — run automatically.
-Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-
-Commit
-
-Uncommitted changes are staged and committed with LLM commit message.
-Use --stage=tracked to stage only tracked files, or --stage=none to commit only what's already staged.
+Examples
-Squash
+Merge current worktree into main:
-Multiple commits are squashed into one (like GitHub's "Squash and merge") with LLM commit message.
-Skip with --no-squash. Safety backup: git reflog show refs/wt-backup/<branch>
+ wt merge
-Rebase
+Keep the worktree after merging:
-Branch is rebased onto target. Conflicts abort the merge immediately.
+ wt merge --no-remove
-Hooks
+Preserve commit history (no squash):
-Pre-merge commands run after rebase (failures abort). Post-merge commands
-run after cleanup (failures logged). Skip all with --no-verify.
+ wt merge --no-squash
-Push
+Skip hooks and approval prompts:
-Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+ wt merge --no-verify --force
-Cleanup
+The Pipeline
-Worktree and branch are removed. Skip with --no-remove.
+wt merge runs these steps in order:
-Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}, {{ target }}
+1. Commit — Stages and commits uncommitted changes with an LLM-generated message. The --stage flag controls what gets staged: all (default), tracked, or none.
-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.
+2. Squash — Combines multiple commits into one (like GitHub's "Squash and merge") with an LLM-generated message. The --no-squash flag preserves individual commits. A backup ref is saved to refs/wt-backup/<branch>.
-Examples
+3. Rebase — Rebases onto the target branch. Conflicts abort the merge immediately.
-Basic merge to main:
+4. Pre-merge hooks — Project-defined commands run after rebase. Failures abort the merge.
- wt merge
+5. Push — Fast-forward push to the local target branch. Non-fast-forward pushes are rejected.
-Merge without squashing:
+6. Cleanup — Removes the worktree and branch. The --no-remove flag keeps the worktree.
- wt merge --no-squash
+7. Post-merge hooks — Project-defined commands run after cleanup. Failures are logged but don't abort.
-Keep worktree after merging:
+Hooks
- wt merge --no-remove
+When merging, hooks run in this order:
-Skip all hooks:
+1. pre-merge — After rebase, before push. Failures abort the merge.
+2. post-merge — After cleanup. Failures are logged but don't abort.
- wt merge --no-verify
+The --no-verify flag skips all hooks. See [Hooks](/hooks/) for configuration details.
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 496689bf1..49bfe4c29 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -47,87 +47,53 @@ Usage: wt remove [OPTIONS] [WORKTREES]...
-v, --verbose
Show commands and debug info
-Operation
+Cleans up finished work by removing worktrees and their branches. Without arguments, removes the current worktree and returns to the main worktree.
-Removes worktree directory, git metadata, and branch. Requires clean working tree.
-
-No arguments (remove current)
-
-- Removes current worktree and switches to main worktree
-- In main worktree: switches to default branch
-
-By name (remove specific)
-
-- Removes specified worktree(s) and branches
-- Current worktree removed last (switches to main first)
-
-Worktree resolution
-
-Arguments are resolved to worktrees 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, use 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 remove foo removes repo.foo/ and the bar branch
-- wt remove bar also works (falls back to branch lookup)
-
-Conflict detection: If path repo.foo/ has a worktree on branch bar, but
-branch foo has a different worktree at repo.bar/, an error is raised.
-
-Special arguments:
+Examples
-- @ - current worktree (by path, works in detached HEAD)
-- - - previous worktree (from switch history)
-- ^ - main worktree
+Remove current worktree and branch:
-Branch deletion
+ wt remove
-By default, branches are deleted only when their content is already in the target branch:
+Remove a specific worktree:
-- no changes beyond the common ancestor — git diff --name-only target...branch is empty:
- no files changed between the merge base of target/branch and the tip of branch.
-- same content as target — git rev-parse branch^{tree} equals git rev-parse target^{tree}:
- both branches point at the same tracked-files snapshot (tree), even if the commits differ.
+ wt remove feature-branch
-This handles workflows where PRs are squash-merged or rebased, which don't preserve
-commit ancestry but do integrate the content. Use -D to delete unintegrated
-branches, or --no-delete-branch to always keep branches.
+Keep the branch after removing the worktree:
-Background removal (default)
+ wt remove --no-delete-branch feature-branch
-- Returns immediately for continued work
-- Logs: .git/wt-logs/{branch}-remove.log
-- Use --no-background for foreground (blocking)
+Remove multiple worktrees:
-Cleanup
+ wt remove old-feature another-branch
-Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (core.fsmonitor=true). No effect on Watchman users.
+Force-delete an unmerged branch:
-Examples
+ wt remove -D experimental
-Remove current worktree and branch:
+Branch Deletion
- wt remove
+By default, branches are deleted only when their content is already integrated into the target branch (typically main). This works correctly with squash-merge and rebase workflows where commit ancestry isn't preserved but the file changes are.
-Remove specific worktree and branch:
+The -D flag overrides this safety check and force-deletes unmerged branches. The --no-delete-branch flag prevents branch deletion entirely.
- wt remove feature-branch
+Background Removal
-Remove worktree but keep branch:
+Removal runs in the background by default — the command returns immediately so work can continue. Logs are written to .git/wt-logs/{branch}-remove.log.
- wt remove --no-delete-branch feature-branch
+The --no-background flag runs removal in the foreground (blocking).
-Remove multiple worktrees:
+How Arguments Are Resolved
- wt remove old-feature another-branch
+Arguments resolve using path-first lookup:
-Remove in foreground (blocking):
+1. Compute the expected path for the argument (using the configured path template)
+2. If a worktree exists at that path, use it (regardless of what branch it's on)
+3. Otherwise, treat the argument as a branch name
- wt remove --no-background feature-branch
+Example: If repo.foo/ exists but is on branch bar:
-Switch to default in main:
+- wt remove foo removes repo.foo/ and the bar branch
+- wt remove bar also works (falls back to branch lookup)
- wt remove # (when already in main worktree)
+Shortcuts: @ (current worktree), - (previous worktree), ^ (main worktree)
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 607b71690..03266b8d9 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -32,9 +32,64 @@ Usage: wt step [OPTIONS] <COMMAND>
post-merge Run post-merge hook
Options:
- -h, --help Print help
+ -h, --help
+ Print help (see a summary with '-h')
Global Options:
- -C <path> Working directory for this command
- --config <path> User config file path
- -v, --verbose Show commands and debug info
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Individual workflow steps for scripting and automation. Each subcommand performs one step of the wt merge pipeline — commit, squash, rebase, push, or run hooks — allowing custom workflows or manual intervention between steps.
+
+Examples
+
+Commit with an LLM-generated message:
+
+ wt step commit
+
+Squash all branch commits into one:
+
+ wt step squash
+
+Run pre-merge hooks (tests, lints):
+
+ wt step pre-merge
+
+Rebase onto main:
+
+ wt step rebase
+
+Use Cases
+
+Custom merge workflow — Run steps individually when wt merge doesn't fit, such as adding manual review between squash and rebase:
+
+ wt step commit
+ wt step squash
+ # manual review here
+ wt step rebase
+ wt step pre-merge
+ wt step push
+
+CI integration — Run hooks explicitly in CI environments:
+
+ wt step pre-merge --force # skip approval prompts
+
+Subcommands
+
+| Command | Description |
+|---------|-------------|
+| commit | Commits uncommitted changes with an [LLM-generated message](/llm-commits/) |
+| squash | Squashes all branch commits into one with an [LLM-generated message](/llm-commits/) |
+| rebase | Rebases the branch onto the target (default: main) |
+| push | Pushes changes to the local target branch |
+| post-create | Runs post-create hooks |
+| post-start | Runs post-start hooks |
+| pre-commit | Runs pre-commit hooks |
+| pre-merge | Runs pre-merge hooks |
+| post-merge | Runs post-merge hooks |
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index 3a1730795..f93399a0d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -32,7 +32,7 @@ Usage: wt step [OPTIONS] <COMMAND>
post-merge Run post-merge hook
Options:
- -h, --help Print help
+ -h, --help Print help (see more with '--help')
Global Options:
-C <path> Working directory for this command
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 013e32193..e9cc5d02e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -57,91 +57,74 @@ Usage: wt switch [OPTIONS] <BRANCH>
-v, --verbose
Show commands and debug info
-Operation
+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.
-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`)
+Examples
-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
+Switch to an existing worktree:
-Hooks
+ wt switch feature-auth
-post-create (sequential, blocking)
+Create a new worktree for a fresh branch:
-- Run after worktree creation, before success message
-- Typically: npm install, cargo build, setup tasks
-- Failures block the operation
-- Skip with --no-verify
+ wt switch --create new-feature
-post-start (parallel, background)
+Create from a specific base branch:
-- 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
+ wt switch --create hotfix --base production
-Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}
+Switch to the previous worktree (like cd -):
-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.
+ wt switch -
-Examples
+Creating Worktrees
-Switch to existing worktree:
+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.
- wt switch feature-branch
+ # Create from main (default)
+ wt switch --create api-refactor
+ 
+ # Create from a specific branch
+ wt switch --create emergency-fix --base release-2.0
+ 
+ # Create and open in editor
+ wt switch --create docs --execute "code ."
+ 
+ # Skip all hooks
+ wt switch --create temp --no-verify
-Create new worktree from main:
+Shortcuts
- wt switch --create new-feature
+Special symbols for common targets:
-Switch to previous worktree:
+| Shortcut | Meaning |
+|----------|---------|
+| - | Previous worktree (like cd -) |
+| @ | Current branch's worktree |
+| ^ | Default branch (main/master) |
- wt switch -
+ wt switch - # Go back to previous worktree
+ wt switch ^ # Switch to main worktree
+ wt switch --create bugfix --base=@ # Branch from current HEAD
-Create from specific base:
+Hooks
- wt switch --create hotfix --base production
+When creating a worktree (--create), hooks run in this order:
-Create and run command:
+1. post-create — Blocking, sequential. Typically: npm install, cargo build
+2. post-start — Background, parallel. Typically: dev servers, file watchers
- wt switch --create docs --execute "code ."
+See [Hooks](/hooks/) for configuration details.
-Skip hooks during creation:
+How Arguments Are Resolved
- wt switch --create temp --no-verify
+Arguments resolve using path-first lookup:
-Shortcuts
+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
-Use @ for current HEAD, - for previous, ^ for main:
+Example: If repo.foo/ exists but is on branch bar:
- 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 --create bugfix --base=@ # Branch from current HEAD
- wt remove @ # Remove current worktree
+- wt switch foo switches to repo.foo/ (the bar branch worktree)
+- wt switch bar also works (falls back to branch lookup)