Skip to content

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

docs: Generate command reference from `help --md`

Maximilian Roosfb791b5c2986
diff --git a/docs/content/advanced.md b/docs/content/advanced.md
index f5f958a74..497a9d253 100644
--- a/docs/content/advanced.md
+++ b/docs/content/advanced.md
@@ -1,8 +1,10 @@
+++
title = "Advanced Features"
-weight = 5
+weight = 6
+++
+Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.
+
## Claude Code Integration
Worktrunk includes a Claude Code plugin for tracking agent status across worktrees.
@@ -65,75 +67,8 @@ Add to `~/.claude/settings.json`:
## Interactive Worktree Picker
-`wt select` opens a fzf-like fuzzy-search worktree picker with diff preview.
-
-### Preview tabs
-
-Toggle with number keys:
-
-1. **Tab 1**: Working tree changes (uncommitted)
-2. **Tab 2**: Commit history (commits not on main highlighted)
-3. **Tab 3**: Branch diff (changes ahead of main)
-
-## Tips & Patterns
-
-### Alias for new worktree + agent
-
-```bash
-alias wsc='wt switch --create --execute=claude'
-wsc new-feature # Creates worktree, runs hooks, launches Claude
-```
-
-### Eliminate cold starts
-
-`post-create` hooks install deps and copy caches. Use copy-on-write on macOS:
-
-```toml
-[post-create]
-"cache" = "cp -c -r ../.cache .cache" # Uses APFS clones
-"install" = "npm ci"
-```
-
-### Local CI gate
-
-`pre-merge` hooks run before merging. Failures abort:
-
-```toml
-[pre-merge]
-"test" = "cargo test"
-"lint" = "cargo clippy -- -D warnings"
-```
-
-### Monitor CI across branches
-
-```bash
-$ wt list --full --branches
-```
-
-Shows PR/CI status for all branches, including those without worktrees.
-
-### JSON API
-
-```bash
-$ wt list --format=json
-```
+`wt select` opens a fuzzy-search worktree picker with diff preview (Unix only).
-For dashboards, statuslines, and scripts.
-
-### Task runners in hooks
-
-```toml
-[post-create]
-"setup" = "task install"
-
-[pre-merge]
-"validate" = "just test lint"
-```
-
-### Stacked branches
-
-```bash
-$ wt switch --create feature-part2 --base=@
-```
+Type to filter, use arrow keys or `j`/`k` to navigate, Enter to switch. Preview tabs show working tree changes, commit history, or branch diff — toggle with `1`/`2`/`3`.
-Branches from current HEAD, not main.
+See [wt select](/commands/#wt-select) for full keyboard shortcuts and details.
diff --git a/docs/content/commands.md b/docs/content/commands.md
index 07c04df83..f2414e2ae 100644
--- a/docs/content/commands.md
+++ b/docs/content/commands.md
@@ -5,251 +5,706 @@ weight = 4
## wt switch
-Switch to an existing worktree or create a new one.
+<!-- ⚠️ AUTO-GENERATED from `wt switch --help-md` — edit source to update -->
+
+```text
+wt switch — Switch to a worktree
+Usage: wt switch [OPTIONS] <BRANCH>
+
+Arguments:
+ <BRANCH>
+ Branch or worktree name
+
+ Shortcuts: '^' (main), '-' (previous), '@' (current)
+
+Options:
+ -c, --create
+ Create a new branch
+
+ -b, --base <BASE>
+ Base branch
+
+ Defaults to default branch.
+
+ -x, --execute <EXECUTE>
+ Command to run after switch
+
+ -f, --force
+ Skip approval prompts
+
+ --no-verify
+ Skip all project hooks
+
+ -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
-```bash
-$ wt switch [OPTIONS] <BRANCH>
```
-### Arguments
+## 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`)
-- `<BRANCH>` — Branch, path, `@` (HEAD), `-` (previous), or `^` (main)
+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
-### Options
+## Hooks
-- `-c, --create` — Create a new branch
-- `-b, --base <BASE>` — Base branch (defaults to default branch)
-- `-x, --execute <EXECUTE>` — Command to run after switch
-- `-f, --force` — Skip approval prompts
-- `--no-verify` — Skip all project hooks
+### post-create (sequential, blocking)
-### Examples
+- Run after worktree creation, before success message
+- Typically: `npm install`, `cargo build`, setup tasks
+- Failures block the operation
+- Skip with `--no-verify`
-```bash
-# Switch to existing worktree
+### 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:
+
+```console
wt switch feature-branch
+```
+
+Create new worktree from main:
-# Create new worktree from main
+```console
wt switch --create new-feature
+```
+
+Switch to previous worktree:
-# Switch to previous worktree
+```console
wt switch -
+```
+
+Create from specific base:
-# Create from specific base
+```console
wt switch --create hotfix --base production
+```
-# Create and run command
+Create and run command:
+
+```console
wt switch --create docs --execute "code ."
```
-### Hooks
+Skip hooks during creation:
-- **post-create** (sequential, blocking) — Runs after creation, before success message
-- **post-start** (parallel, background) — Spawned after success, logs to `.git/wt-logs/`
+```console
+wt switch --create temp --no-verify
+```
+
+## Shortcuts
+
+Use `@` for current HEAD, `-` for previous, `^` for main:
+
+```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 --create bugfix --base=@ # Branch from current HEAD
+wt remove @ # Remove current worktree
+```
+
+<!-- END AUTO-GENERATED -->
---
## wt merge
-Merge worktree into target branch with full workflow automation.
+<!-- ⚠️ AUTO-GENERATED from `wt merge --help-md` — edit source to update -->
+
+```text
+wt merge — Merge worktree into target branch
+Usage: wt merge [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-squash
+ Skip commit squashing
+
+ --no-commit
+ Skip commit, squash, and rebase
+
+ --no-remove
+ Keep worktree after merge
+
+ --no-verify
+ Skip all project hooks
+
+ -f, --force
+ Skip approval prompts
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ -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
-```bash
-$ wt merge [OPTIONS] [TARGET]
```
-### Arguments
+## Operation
+
+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.
+
+### Squash
+
+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>`
-- `[TARGET]` — Target branch (defaults to default branch)
+### Rebase
-### Options
+Branch is rebased onto target. Conflicts abort the merge immediately.
-- `--no-squash` — Skip commit squashing
-- `--no-commit` — Skip commit, squash, and rebase
-- `--no-remove` — Keep worktree after merge
-- `--no-verify` — Skip all project hooks
-- `-f, --force` — Skip approval prompts
-- `--stage <STAGE>` — What to stage: `all` (default), `tracked`, `none`
+### Hooks
+
+Pre-merge commands run after rebase (failures abort). Post-merge commands
+run after cleanup (failures logged). Skip all with `--no-verify`.
+
+### Push
+
+Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
+
+### Cleanup
-### Operation
+Worktree and branch are removed. Skip with `--no-remove`.
-1. **Commit** — Stage and commit with LLM message
-2. **Squash** — Combine commits into one
-3. **Rebase** — Rebase onto target
-4. **Pre-merge hooks** — Run tests/lints
-5. **Push** — Fast-forward to target
-6. **Cleanup** — Remove worktree and branch
-7. **Post-merge hooks** — Final automation
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
-### Examples
+**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`.
-```bash
-# Full merge to main
+## Examples
+
+Basic merge to main:
+
+```console
wt merge
+```
+
+Merge without squashing:
+
+```console
+wt merge --no-squash
+```
+
+Keep worktree after merging:
-# Keep worktree after merging
+```console
wt merge --no-remove
+```
-# Skip hooks
-wt merge --no-verify
+Skip all hooks:
-# Merge without squashing
-wt merge --no-squash
+```console
+wt merge --no-verify
```
+<!-- END AUTO-GENERATED -->
+
---
## wt remove
-Remove worktree and optionally delete branch.
+<!-- ⚠️ AUTO-GENERATED from `wt remove --help-md` — edit source to update -->
+
+```text
+wt remove — Remove worktree and branch
+Usage: wt remove [OPTIONS] [WORKTREES]...
+
+Arguments:
+ [WORKTREES]...
+ Worktree or branch (@ for current)
+
+Options:
+ --no-delete-branch
+ Keep branch after removal
+
+ -D, --force-delete
+ Delete unmerged branches
+
+ --no-background
+ Run removal in foreground
+
+ -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
-```bash
-$ wt remove [OPTIONS] [WORKTREES]...
```
-### Arguments
+## 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
-- `[WORKTREES]...` — Worktree or branch (`@` for current)
+### By name (remove specific)
-### Options
+- Removes specified worktree(s) and branches
+- Current worktree removed last (switches to main first)
-- `--no-delete-branch` — Keep branch after removal
-- `-D, --force-delete` — Delete unmerged branches
-- `--no-background` — Run removal in foreground
+### 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
-- Same content as target (handles squash/rebase merges)
+- 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)
-Use `-D` to force delete unmerged branches.
+### Cleanup
-### Examples
+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.
-```bash
-# Remove current worktree
+## Examples
+
+Remove current worktree and branch:
+
+```console
wt remove
+```
-# Remove specific worktree
+Remove specific worktree and branch:
+
+```console
wt remove feature-branch
+```
-# Keep the branch
+Remove worktree but keep branch:
+
+```console
wt remove --no-delete-branch feature-branch
+```
+
+Remove multiple worktrees:
-# Remove multiple
+```console
wt remove old-feature another-branch
```
+Remove in foreground (blocking):
+
+```console
+wt remove --no-background feature-branch
+```
+
+Switch to default in main:
+
+```console
+wt remove # (when already in main worktree)
+```
+
+<!-- END AUTO-GENERATED -->
+
---
## wt list
-Show all worktrees and optionally branches.
+<!-- ⚠️ AUTO-GENERATED from `wt list --help-md` — edit source to update -->
-```bash
-$ wt list [OPTIONS]
-```
+```text
+wt list — List worktrees and optionally branches
+Usage: wt list [OPTIONS]
+ wt list <COMMAND>
+
+Commands:
+ statusline Single-line status for shell prompts
+
+Options:
+ --format <FORMAT>
+ Output format (table, json)
+
+ [default: table]
+
+ --branches
+ Include branches without worktrees
-### Options
+ --remotes
+ Include remote branches
-- `--format <FORMAT>` — Output format: `table` (default), `json`
-- `--branches` — Include branches without worktrees
-- `--remotes` — Include remote branches
-- `--full` — Show CI, conflicts, diffs
-- `--progressive` — Show fast info first, update with slow info
+ --full
+ Show CI, conflicts, diffs
-### Columns
+ --progressive
+ Show fast info immediately, update with slow info
-| Column | Description |
-|--------|-------------|
-| Branch | Branch name |
-| Status | Quick status symbols |
-| HEAD± | Uncommitted changes vs HEAD |
-| main↕ | Commits ahead/behind main |
-| main…± | Line diffs ahead of main (with `--full`) |
-| Path | Worktree directory |
-| Remote⇅ | Commits ahead/behind remote |
-| CI | Pipeline status (with `--full`) |
-| Commit | Short hash |
-| Age | Time since last commit |
-| Message | Last commit message |
+ Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
-### Status Symbols
+ -h, --help
+ Print help (see a summary with '-h')
-- `+` Staged files
-- `!` Modified files
-- `?` Untracked files
-- `✖` Merge conflicts
-- `⊘` Would conflict with main
-- `≡` Matches main content
-- `_` No commits
-- `↑↓↕` Ahead/behind/diverged from main
-- `⇡⇣⇅` Ahead/behind/diverged from remote
+Global Options:
+ -C <path>
+ Working directory for this command
-### JSON Output
+ --config <path>
+ User config file path
-```bash
-# Get current worktree
-wt list --format=json | jq '.[] | select(.is_current)'
+ -v, --verbose
+ Show commands and debug info
+```
+
+## 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)
+
+## Status Symbols
+
+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).
+
+## JSON Output
+
+Use `--format=json` for structured data. Each object contains two status maps
+with the same fields in the same order as Status Symbols above:
+
+**`status`** - variant names for querying:
+
+- `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_status`: string (optional)
+
+**`status_symbols`** - Unicode symbols for display (same fields, plus `worktree_attrs`: ⎇/⌫/⊠)
+
+Note: `locked` and `prunable` are top-level fields on worktree objects, not in status.
+
+**Worktree position fields** (for identifying special worktrees):
+
+- `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)
+
+**Query examples:**
+
+```console
# Find worktrees with conflicts
-wt list --format=json | jq '.[] | select(.status.branch_state == "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 != "")'
+
+# 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)'
+
+# Get current worktree info (useful for statusline tools)
+jq '.[] | select(.is_current == true)'
```
+<!-- END AUTO-GENERATED -->
+
---
## wt config
-Manage configuration and shell integration.
+<!-- ⚠️ AUTO-GENERATED from `wt config --help-md` — edit source to update -->
+
+```text
+wt config — Manage configuration and shell integration
+Usage: wt config [OPTIONS] <COMMAND>
+
+Commands:
+ shell Shell integration setup
+ create Create user configuration file
+ show Show configuration files & locations
+ cache Manage caches (CI status, default branch)
+ status Manage branch status markers
+ approvals Manage command approvals
+
+Options:
+ -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
-```bash
-$ wt config <COMMAND>
```
-### Subcommands
+## Setup Guide
-- `shell install` — Install shell integration
-- `shell init <SHELL>` — Output shell init script
-- `create` — Create user config file with examples
-- `show` — Show config file locations
-- `cache` — Manage caches
-- `status` — Manage branch status markers
-- `approvals` — Manage command approvals
+1. Set up shell integration
----
+ ```console
+ wt config shell install
+ ```
-## wt step
+ Or manually add to the shell config:
+
+ ```console
+ eval "$(wt config shell init bash)"
+ ```
+
+2. (Optional) Create user config file
+
+ ```console
+ wt config create
+ ```
+
+ This creates `~/.config/worktrunk/config.toml` with examples.
+
+3. (Optional) Enable LLM commit messages
-Building blocks for custom workflows.
+ Install: `uv tool install -U llm`
+ Configure: `llm keys set anthropic`
+ Add to user config:
-```bash
-$ wt step <COMMAND>
+ ```toml
+ [commit-generation]
+ command = "llm"
+ ```
+
+## LLM Setup Details
+
+For Claude:
+
+```console
+llm install llm-anthropic
+llm keys set anthropic
+llm models default claude-haiku-4-5-20251001
+```
+
+For OpenAI:
+
+```console
+llm keys set openai
```
-### Subcommands
+Use `wt config show` to view the current configuration.
+Docs: <https://llm.datasette.io/> | <https://github.com/sigoden/aichat>
+
+## Configuration Files
+
+**User config**:
+
+- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
+- Run `wt config create --help` to view documented examples
+
+**Project config**:
-- `commit` — Commit changes with LLM message
-- `squash` — Squash commits with LLM message
-- `push` — Push to local target branch
-- `rebase` — Rebase onto target
-- `post-create` — Run post-create hook
-- `post-start` — Run post-start hook
-- `pre-commit` — Run pre-commit hook
-- `pre-merge` — Run pre-merge hook
-- `post-merge` — Run post-merge hook
+- Location: `.config/wt.toml` in repository root
+- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+
+<!-- END AUTO-GENERATED -->
+
+---
+
+## wt step
+
+<!-- ⚠️ AUTO-GENERATED from `wt step --help-md` — edit source to update -->
+
+```text
+wt step — Workflow building blocks
+Usage: wt step [OPTIONS] <COMMAND>
+
+Commands:
+ commit Commit changes with LLM commit message
+ squash Squash commits with LLM commit message
+ push Push changes to local target branch
+ rebase Rebase onto target
+ post-create Run post-create hook
+ post-start Run post-start hook
+ pre-commit Run pre-commit hook
+ pre-merge Run pre-merge hook
+ post-merge Run post-merge hook
+
+Options:
+ -h, --help Print help
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose Show commands and debug info
+```
+
+<!-- END AUTO-GENERATED -->
---
## wt select
-Interactive worktree picker with diff preview. Unix only.
+Interactive fzf-like fuzzy-search worktree picker with diff preview. Unix only.
+
+Navigate worktrees with keyboard shortcuts:
+- Arrow keys or `j`/`k` to move between worktrees
+- Enter to switch to selected worktree
+- `Esc` or `q` to cancel
+
+### Preview tabs
-Preview tabs (toggle with `1`/`2`/`3`):
+Toggle with number keys:
-1. Working tree changes (uncommitted)
-2. Commit history (commits not on main highlighted)
-3. Branch diff (changes ahead of main)
+| Key | Tab | Content |
+|-----|-----|---------|
+| `1` | Working tree | Uncommitted changes (like `git diff`) |
+| `2` | Commit history | Recent commits; commits not on main are highlighted |
+| `3` | Branch diff | Changes ahead of main (cumulative diff) |
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 82af3ab8e..4b2bbf757 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -146,6 +146,12 @@ wt config shell init fish | source
## Environment Variables
-- `WORKTRUNK_CONFIG_PATH` — Override user config location
-- `NO_COLOR` — Disable colored output
-- `CLICOLOR_FORCE` — Force colored output
+Override default behavior with environment variables:
+
+| Variable | Effect |
+|----------|--------|
+| `WORKTRUNK_CONFIG_PATH` | Override user config location (default: `~/.config/worktrunk/config.toml`) |
+| `NO_COLOR` | Disable colored output |
+| `CLICOLOR_FORCE` | Force colored output even when not a TTY |
+
+These follow standard conventions — `NO_COLOR` is the [no-color.org](https://no-color.org/) standard.
diff --git a/docs/content/faq.md b/docs/content/faq.md
index b2da00096..d11048195 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -1,6 +1,6 @@
+++
title = "FAQ"
-weight = 6
+weight = 7
+++
## What commands does Worktrunk execute?
diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md
index 1e626fbab..95dda7176 100644
--- a/docs/content/quickstart.md
+++ b/docs/content/quickstart.md
@@ -5,11 +5,20 @@ weight = 1
## Install
+**Homebrew (macOS):**
+
```bash
-$ cargo install worktrunk
+$ brew install max-sixty/worktrunk/wt
$ wt config shell install # allows commands to change directories
```
+**Cargo:**
+
+```bash
+$ cargo install worktrunk
+$ wt config shell install
+```
+
## Create a worktree
```bash
@@ -67,6 +76,6 @@ $ wt remove @ # Remove current worktree
## Next steps
-- Learn [why worktrees](/concepts/) and how Worktrunk improves on plain git
+- Understand [why worktrees matter](/concepts/) and how Worktrunk improves on plain git
- Set up [project hooks](/configuration/) for automated setup
- Use [LLM commit messages](/configuration/#llm-commit-messages) for auto-generated commits
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
new file mode 100644
index 000000000..256163a3d
--- /dev/null
+++ b/docs/content/tips-patterns.md
@@ -0,0 +1,118 @@
++++
+title = "Tips & Patterns"
+weight = 5
++++
+
+Practical recipes for common Worktrunk workflows.
+
+## Alias for new worktree + agent
+
+Create a worktree and launch Claude in one command:
+
+```bash
+alias wsc='wt switch --create --execute=claude'
+wsc new-feature # Creates worktree, runs hooks, launches Claude
+```
+
+## Eliminate cold starts
+
+`post-create` hooks install deps and copy caches. On macOS, use copy-on-write for instant cache cloning:
+
+```toml
+[post-create]
+"cache" = "cp -c -r ../.cache .cache" # APFS clones (instant, no disk space)
+"install" = "npm ci"
+```
+
+See [`.config/wt.toml`](https://github.com/max-sixty/worktrunk/blob/main/.config/wt.toml) on GitHub for a complete example.
+
+## Local CI gate
+
+`pre-merge` hooks run before merging. Failures abort the merge:
+
+```toml
+[pre-merge]
+"lint" = "uv run ruff check"
+"test" = "uv run pytest"
+```
+
+This catches issues locally before pushing — like having CI run on your machine.
+
+## Track agent status
+
+Custom emoji markers show agent state in `wt list`. The Claude Code plugin sets these automatically:
+
+```
++ feature-api ↑ 🤖 ↑1 ./repo.feature-api
++ review-ui ? ↑ 💬 ↑1 ./repo.review-ui
+```
+
+- `🤖` — Claude is working
+- `💬` — Claude is waiting for input
+
+Set status manually for any workflow:
+
+```bash
+wt config status set "🚧" # Current branch
+wt config status set "✅" --branch feature # Specific branch
+git config worktrunk.status.feature "💬" # Direct git config
+```
+
+See [Claude Code Integration](/advanced/#claude-code-integration) for plugin installation.
+
+## Monitor CI across branches
+
+```bash
+wt list --full --branches
+```
+
+Shows PR/CI status for all branches, including those without worktrees. The CI column links to PR pages in terminals with hyperlink support.
+
+## JSON API
+
+```bash
+wt list --format=json
+```
+
+Structured output for dashboards, statuslines, and scripts. See [wt list](/commands/#wt-list) for query examples.
+
+## Task runners in hooks
+
+Reference Taskfile/Justfile/Makefile in hooks:
+
+```toml
+[post-create]
+"setup" = "task install"
+
+[pre-merge]
+"validate" = "just test lint"
+```
+
+## Shortcuts
+
+Special arguments work across all commands:
+
+| Shortcut | Meaning |
+|----------|---------|
+| `^` | default branch (main/master) |
+| `@` | current branch/worktree |
+| `-` | previous worktree (like `cd -`) |
+
+Examples:
+
+```bash
+wt switch --create hotfix --base=@ # Branch from current HEAD
+wt switch --create feature --base=^ # Branch from main (default)
+wt switch - # Switch to previous worktree
+wt remove @ # Remove current worktree
+```
+
+## Stacked branches
+
+Branch from current HEAD instead of main:
+
+```bash
+wt switch --create feature-part2 --base=@
+```
+
+Creates a worktree that builds on the current branch's changes.
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 4fafb1739..583821bca 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -484,6 +484,33 @@ fn test_config_example_templates_are_in_sync() {
}
}
+/// Update help markers in a file (for both README.md and docs pages)
+fn sync_help_markers(file_path: &Path, project_root: &Path) -> Result<usize, Vec<String>> {
+ let content = fs::read_to_string(file_path)
+ .map_err(|e| vec![format!("Failed to read {}: {}", file_path.display(), e)])?;
+
+ let project_root_clone = project_root.to_path_buf();
+ match update_readme_section(
+ &content,
+ &HELP_MARKER_PATTERN,
+ |cmd, _current| get_help_output(cmd, &project_root_clone),
+ ("", ""),
+ ) {
+ Ok((new_content, updated_count, _total_count)) => {
+ if updated_count > 0 {
+ fs::write(file_path, &new_content).unwrap();
+ println!(
+ "✅ Updated {} help sections in {}",
+ updated_count,
+ file_path.display()
+ );
+ }
+ Ok(updated_count)
+ }
+ Err(errs) => Err(errs),
+ }
+}
+
#[test]
fn test_readme_examples_are_in_sync() {
let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
@@ -557,3 +584,21 @@ fn test_readme_examples_are_in_sync() {
);
}
}
+
+#[test]
+fn test_docs_commands_are_in_sync() {
+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));
+ let commands_path = project_root.join("docs/content/commands.md");
+
+ if !commands_path.exists() {
+ // Skip if docs directory doesn't exist
+ return;
+ }
+
+ match sync_help_markers(&commands_path, project_root) {
+ Ok(_) => {}
+ Err(errors) => {
+ panic!("Docs commands are out of sync:\n\n{}\n", errors.join("\n"));
+ }
+ }
+}