Skip to content

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

Docs: Split command pages with --help-page generation

Maximilian Roos3f81f285ac7b
diff --git a/docs/content/advanced.md b/docs/content/advanced.md
index c1bedaf99..bf9bd838e 100644
--- a/docs/content/advanced.md
+++ b/docs/content/advanced.md
@@ -1,6 +1,9 @@
+++
title = "Advanced Features"
-weight = 8
+weight = 23
+
+[extra]
+group = "Reference"
+++
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.
diff --git a/docs/content/commands.md b/docs/content/commands.md
deleted file mode 100644
index 41cd1e17a..000000000
--- a/docs/content/commands.md
+++ /dev/null
@@ -1,713 +0,0 @@
-+++
-title = "Commands Reference"
-weight = 6
-+++
-
-## wt switch
-
-<!-- ⚠️ AUTO-GENERATED from `wt switch --help-md` — edit source to update -->
-
-```
-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
-
-```
-
-### 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`.
-
-### Examples
-
-Switch to existing worktree:
-
-```bash
-wt switch feature-branch
-```
-
-Create new worktree from main:
-
-```bash
-wt switch --create new-feature
-```
-
-Switch to previous worktree:
-
-```bash
-wt switch -
-```
-
-Create from specific base:
-
-```bash
-wt switch --create hotfix --base production
-```
-
-Create and run command:
-
-```bash
-wt switch --create docs --execute "code ."
-```
-
-Skip hooks during creation:
-
-```bash
-wt switch --create temp --no-verify
-```
-
-### Shortcuts
-
-Use `@` for current HEAD, `-` for previous, `^` for main:
-
-```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 --create bugfix --base=@ # Branch from current HEAD
-wt remove @ # Remove current worktree
-```
-
-<!-- END AUTO-GENERATED -->
-
----
-
-## wt merge
-
-<!-- ⚠️ AUTO-GENERATED from `wt merge --help-md` — edit source to update -->
-
-```
-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
-
-```
-
-### 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>`
-
-#### Rebase
-
-Branch is rebased onto target. Conflicts abort the merge immediately.
-
-#### 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
-
-Worktree and branch are removed. Skip with `--no-remove`.
-
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
-
-**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
-
-Basic merge to main:
-
-```bash
-wt merge
-```
-
-Merge without squashing:
-
-```bash
-wt merge --no-squash
-```
-
-Keep worktree after merging:
-
-```bash
-wt merge --no-remove
-```
-
-Skip all hooks:
-
-```bash
-wt merge --no-verify
-```
-
-<!-- END AUTO-GENERATED -->
-
----
-
-## wt remove
-
-<!-- ⚠️ AUTO-GENERATED from `wt remove --help-md` — edit source to update -->
-
-```
-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
-
-```
-
-### 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.
-
-### Examples
-
-Remove current worktree and branch:
-
-```bash
-wt remove
-```
-
-Remove specific worktree and branch:
-
-```bash
-wt remove feature-branch
-```
-
-Remove worktree but keep branch:
-
-```bash
-wt remove --no-delete-branch feature-branch
-```
-
-Remove multiple worktrees:
-
-```bash
-wt remove old-feature another-branch
-```
-
-Remove in foreground (blocking):
-
-```bash
-wt remove --no-background feature-branch
-```
-
-Switch to default in main:
-
-```bash
-wt remove # (when already in main worktree)
-```
-
-<!-- END AUTO-GENERATED -->
-
----
-
-## wt list
-
-<!-- ⚠️ AUTO-GENERATED from `wt list --help-md` — edit source to update -->
-
-```
-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
-
- --remotes
- Include remote branches
-
- --full
- Show CI, conflicts, diffs
-
- --progressive
- Show fast info immediately, update with slow info
-
- Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
-
- -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
-
-```
-
-### 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_marker`: 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:**
-
-```bash
-# 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 != "")'
-
-# Get branches ahead of main
-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
-
-<!-- ⚠️ AUTO-GENERATED from `wt config --help-md` — edit source to update -->
-
-```
-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)
- var Get or set runtime variables (stored in git config)
- 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
-
-```
-
-### Setup Guide
-
-1. Set up shell integration
-
- ```bash
- wt config shell install
- ```
-
- Or manually add to the shell config:
-
- ```bash
- eval "$(wt config shell init bash)"
- ```
-
-2. (Optional) Create user config file
-
- ```bash
- wt config create
- ```
-
- This creates `~/.config/worktrunk/config.toml` with examples.
-
-3. (Optional) Enable LLM commit messages
-
- Install: `uv tool install -U llm`
- Configure: `llm keys set anthropic`
- Add to user config:
-
- ```toml
- [commit-generation]
- command = "llm"
- ```
-
-### LLM Setup Details
-
-For Claude:
-
-```bash
-llm install llm-anthropic
-llm keys set anthropic
-llm models default claude-haiku-4-5-20251001
-```
-
-For OpenAI:
-
-```bash
-llm keys set openai
-```
-
-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**:
-
-- 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 -->
-
-```
-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
-
-<!-- TODO: This content should come from `wt select --help-md` like other commands.
- Add the keyboard shortcuts to the help text in the codebase. -->
-
-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
-
-Toggle with number keys:
-
-| 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/config.md b/docs/content/config.md
new file mode 100644
index 000000000..ea3f94eac
--- /dev/null
+++ b/docs/content/config.md
@@ -0,0 +1,104 @@
++++
+title = "wt config"
+weight = 15
+
+[extra]
+group = "Commands"
++++
+
+## Setup Guide
+
+1. Set up shell integration
+
+ ```bash
+ wt config shell install
+ ```
+
+ Or manually add to the shell config:
+
+ ```bash
+ eval "$(wt config shell init bash)"
+ ```
+
+2. (Optional) Create user config file
+
+ ```bash
+ wt config create
+ ```
+
+ This creates `~/.config/worktrunk/config.toml` with examples.
+
+3. (Optional) Enable LLM commit messages
+
+ Install: `uv tool install -U llm`
+ Configure: `llm keys set anthropic`
+ Add to user config:
+
+ ```toml
+ [commit-generation]
+ command = "llm"
+ ```
+
+## LLM Setup Details
+
+For Claude:
+
+```bash
+llm install llm-anthropic
+llm keys set anthropic
+llm models default claude-haiku-4-5-20251001
+```
+
+For OpenAI:
+
+```bash
+llm keys set openai
+```
+
+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**:
+
+- Location: `.config/wt.toml` in repository root
+- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt config --help-page` — edit cli.rs to update -->
+
+```bash
+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)
+ var Get or set runtime variables (stored in git config)
+ 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
+```
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 3b63088cd..2be839d45 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -1,6 +1,9 @@
+++
title = "Configuration"
-weight = 4
+weight = 20
+
+[extra]
+group = "Reference"
+++
Worktrunk uses two configuration files:
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 610d01f1e..67e21e5a6 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -1,6 +1,9 @@
+++
title = "FAQ"
-weight = 9
+weight = 25
+
+[extra]
+group = "Reference"
+++
## What commands does Worktrunk execute?
diff --git a/docs/content/hooks.md b/docs/content/hooks.md
index dd5e196db..818af8ad6 100644
--- a/docs/content/hooks.md
+++ b/docs/content/hooks.md
@@ -1,6 +1,9 @@
+++
title = "Hooks"
-weight = 5
+weight = 21
+
+[extra]
+group = "Reference"
+++
Hooks automate setup and validation at worktree lifecycle events. They're defined in `.config/wt.toml` (project config) and run automatically during `wt switch --create` and `wt merge`.
diff --git a/docs/content/list.md b/docs/content/list.md
new file mode 100644
index 000000000..9586f611a
--- /dev/null
+++ b/docs/content/list.md
@@ -0,0 +1,147 @@
++++
+title = "wt list"
+weight = 11
+
+[extra]
+group = "Commands"
++++
+
+## 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_marker`: 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:**
+
+```bash
+# 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 != "")'
+
+# Get branches ahead of main
+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)'
+```
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt list --help-page` — edit cli.rs to update -->
+
+```bash
+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
+
+ --remotes
+ Include remote branches
+
+ --full
+ Show CI, conflicts, diffs
+
+ --progressive
+ Show fast info immediately, update with slow info
+
+ Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
+
+ -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
+```
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
index 80433faa0..83b92dfa4 100644
--- a/docs/content/llm-commits.md
+++ b/docs/content/llm-commits.md
@@ -1,6 +1,9 @@
+++
title = "LLM Commit Messages"
-weight = 5
+weight = 22
+
+[extra]
+group = "Reference"
+++
Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with `wt merge` and `wt step commit`.
diff --git a/docs/content/merge.md b/docs/content/merge.md
new file mode 100644
index 000000000..1c485dc24
--- /dev/null
+++ b/docs/content/merge.md
@@ -0,0 +1,124 @@
++++
+title = "wt merge"
+weight = 12
+
+[extra]
+group = "Commands"
++++
+
+## 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>`
+
+### Rebase
+
+Branch is rebased onto target. Conflicts abort the merge immediately.
+
+### 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
+
+Worktree and branch are removed. Skip with `--no-remove`.
+
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+
+**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
+
+Basic merge to main:
+
+```bash
+wt merge
+```
+
+Merge without squashing:
+
+```bash
+wt merge --no-squash
+```
+
+Keep worktree after merging:
+
+```bash
+wt merge --no-remove
+```
+
+Skip all hooks:
+
+```bash
+wt merge --no-verify
+```
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
+
+```bash
+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
+```
diff --git a/docs/content/remove.md b/docs/content/remove.md
new file mode 100644
index 000000000..a2d83a20d
--- /dev/null
+++ b/docs/content/remove.md
@@ -0,0 +1,142 @@
++++
+title = "wt remove"
+weight = 13
+
+[extra]
+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.
+
+## Examples
+
+Remove current worktree and branch:
+
+```bash
+wt remove
+```
+
+Remove specific worktree and branch:
+
+```bash
+wt remove feature-branch
+```
+
+Remove worktree but keep branch:
+
+```bash
+wt remove --no-delete-branch feature-branch
+```
+
+Remove multiple worktrees:
+
+```bash
+wt remove old-feature another-branch
+```
+
+Remove in foreground (blocking):
+
+```bash
+wt remove --no-background feature-branch
+```
+
+Switch to default in main:
+
+```bash
+wt remove # (when already in main worktree)
+```
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt remove --help-page` — edit cli.rs to update -->
+
+```bash
+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
+```
diff --git a/docs/content/select.md b/docs/content/select.md
new file mode 100644
index 000000000..9b83bbd5f
--- /dev/null
+++ b/docs/content/select.md
@@ -0,0 +1,36 @@
++++
+title = "wt select"
+weight = 14
+
+[extra]
+group = "Commands"
++++
+
+
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt select --help-page` — edit cli.rs to update -->
+
+```bash
+wt select - Interactive worktree selector
+
+Toggle preview tabs with 1/2/3 keys. Toggle preview visibility with alt-p.
+Usage: wt select [OPTIONS]
+
+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
+```
diff --git a/docs/content/step.md b/docs/content/step.md
new file mode 100644
index 000000000..8a8ff97f5
--- /dev/null
+++ b/docs/content/step.md
@@ -0,0 +1,39 @@
++++
+title = "wt step"
+weight = 16
+
+[extra]
+group = "Commands"
++++
+
+
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt step --help-page` — edit cli.rs to update -->
+
+```bash
+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
+```
diff --git a/docs/content/switch.md b/docs/content/switch.md
new file mode 100644
index 000000000..8422164f9
--- /dev/null
+++ b/docs/content/switch.md
@@ -0,0 +1,158 @@
++++
+title = "wt switch"
+weight = 10
+
+[extra]
+group = "Commands"
++++
+
+## Operation
+
+### Worktree resolution
+
+Arguments are resolved using **path-first lookup**:
+
+1. Compute the expected path for the argument (using the configured path template)
+2. If a worktree exists at that path, switch to it (regardless of what branch it's on)
+3. Otherwise, treat the argument as a branch name
+
+**Example**: If `repo.foo/` exists but is on branch `bar`:
+
+- `wt switch foo` switches to `repo.foo/` (the `bar` branch worktree)
+- `wt switch bar` also works (falls back to branch lookup)
+
+### Switching to Existing Worktree
+
+- If worktree exists at expected path or for branch, changes directory via shell integration
+- No hooks run
+- No branch creation
+
+### Creating New Worktree (`--create`)
+
+1. Creates new branch (defaults to current default branch as base)
+2. Creates worktree in configured location (default: `../{{ main_worktree }}.{{ branch }}`)
+3. Runs post-create hooks sequentially (blocking)
+4. Shows success message
+5. Spawns post-start hooks in background (non-blocking)
+6. Changes directory to new worktree via shell integration
+
+## Hooks
+
+### post-create (sequential, blocking)
+
+- Run after worktree creation, before success message
+- Typically: `npm install`, `cargo build`, setup tasks
+- Failures block the operation
+- Skip with `--no-verify`
+
+### post-start (parallel, background)
+
+- Spawned after success message shown
+- Typically: dev servers, file watchers, editors
+- Run in background, failures logged but don't block
+- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`
+- Skip with `--no-verify`
+
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`
+
+**Security:** Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use `--force` to bypass prompts.
+See `wt config approvals --help`.
+
+## Examples
+
+Switch to existing worktree:
+
+```bash
+wt switch feature-branch
+```
+
+Create new worktree from main:
+
+```bash
+wt switch --create new-feature
+```
+
+Switch to previous worktree:
+
+```bash
+wt switch -
+```
+
+Create from specific base:
+
+```bash
+wt switch --create hotfix --base production
+```
+
+Create and run command:
+
+```bash
+wt switch --create docs --execute "code ."
+```
+
+Skip hooks during creation:
+
+```bash
+wt switch --create temp --no-verify
+```
+
+## Shortcuts
+
+Use `@` for current HEAD, `-` for previous, `^` for main:
+
+```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 --create bugfix --base=@ # Branch from current HEAD
+wt remove @ # Remove current worktree
+```
+
+---
+
+## Command Reference
+
+<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
+
+```bash
+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
+```
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index c72d396cd..70688ac19 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -1,6 +1,9 @@
+++
title = "Tips & Patterns"
-weight = 7
+weight = 24
+
+[extra]
+group = "Reference"
+++
Practical recipes for common Worktrunk workflows.
diff --git a/docs/sass/custom.scss b/docs/sass/custom.scss
index 83d89d9d2..0279373d1 100644
--- a/docs/sass/custom.scss
+++ b/docs/sass/custom.scss
@@ -110,15 +110,15 @@ header {
nav {
display: flex;
align-items: center;
- gap: 0.25rem;
+ gap: 0;
}
// Navigation links
.nav-item {
- font-size: 0.9rem;
+ font-size: 0.85rem;
font-weight: 500;
color: var(--wt-color-text-muted);
- padding: 0.25rem 0.5rem;
+ padding: 0.2rem 0.4rem;
border-radius: 999px;
transition: color 150ms, background 150ms;
@@ -415,15 +415,29 @@ table {
overscroll-behavior: contain; // Trap scroll events within TOC
}
+.toc-group-label {
+ font-size: 0.7rem;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--wt-color-text-soft);
+ padding: 0.5rem 0.5rem 0.15rem;
+ margin: 0.25rem 0.5rem 0;
+
+ &:first-child {
+ margin-top: 0;
+ }
+}
+
.toc-item {
- padding: 0.1rem 0.5rem;
+ padding: 0;
margin: 0 0.5rem;
a {
display: block;
- padding: 0.2rem 0.5rem;
+ padding: 0.15rem 0.5rem;
border-radius: 0.35rem;
- font-size: 0.875rem;
+ font-size: 0.8rem;
color: var(--wt-color-text-muted);
transition: all 150ms;
@@ -444,11 +458,11 @@ table {
}
.toc-item-child {
- padding: 0 0.5rem 0.1rem 1.25rem;
+ padding: 0 0.5rem 0 1rem;
margin: 0 0.5rem;
a {
- font-size: 0.9rem;
+ font-size: 0.75rem;
color: var(--wt-color-text-soft);
padding: 0.1rem 0.4rem;
border-radius: 0.3rem;
@@ -463,10 +477,10 @@ table {
}
&.nested {
- padding-left: 2.5rem;
+ padding-left: 2rem;
a {
- font-size: 0.85rem;
+ font-size: 0.7rem;
}
}
}
diff --git a/docs/templates/page.html b/docs/templates/page.html
index a523c2939..d7b1980cd 100644
--- a/docs/templates/page.html
+++ b/docs/templates/page.html
@@ -6,8 +6,17 @@
{% set docs_section = get_section(path="_index.md") %}
<div class="toc">
<div class="toc-sticky">
+ {% set current_group = "" %}
{% for doc_page in docs_section.pages %}
{% set is_current = doc_page.permalink == page.permalink %}
+ {% set page_group = doc_page.extra.group | default(value="") %}
+
+ {# Show group label when group changes #}
+ {% if page_group != current_group and page_group != "" %}
+ <div class="toc-group-label">{{ page_group }}</div>
+ {% set_global current_group = page_group %}
+ {% endif %}
+
<div class="toc-item">
<a class="subtext {% if is_current %}active{% endif %}" href="{{ doc_page.permalink | safe }}">
{{ doc_page.title }}
diff --git a/src/main.rs b/src/main.rs
index d87ec45fc..5e7ea820d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -54,6 +54,12 @@ fn maybe_handle_help_with_pager() -> bool {
let args: Vec<String> = std::env::args().collect();
+ // Check for --help-page flag (output full doc page with frontmatter)
+ if args.iter().any(|a| a == "--help-page") {
+ handle_help_page(&args);
+ process::exit(0);
+ }
+
// Check for --help-md flag (output raw markdown without ANSI rendering)
if args.iter().any(|a| a == "--help-md") {
let mut cmd = cli::build_command();
@@ -127,6 +133,148 @@ fn maybe_handle_help_with_pager() -> bool {
}
}
+/// Generate a full documentation page for a command.
+///
+/// Output format:
+/// ```markdown
+/// +++
+/// title = "Merging"
+/// weight = 5
+/// +++
+///
+/// [after_long_help content - the conceptual docs]
+///
+/// ---
+///
+/// ## Command Reference
+///
+/// ```bash
+/// wt merge — ...
+/// Usage: ...
+/// ```
+/// ```
+///
+/// This is used to generate docs/content/merge.md etc from the source.
+fn handle_help_page(args: &[String]) {
+ use clap::ColorChoice;
+ use clap::error::ErrorKind;
+
+ let mut cmd = cli::build_command();
+ cmd = cmd.color(ColorChoice::Never);
+
+ // Find the subcommand name (the arg before --help-page, or after wt)
+ let subcommand = args
+ .iter()
+ .filter(|a| *a != "--help-page" && !a.starts_with('-') && !a.ends_with("/wt"))
+ .find(|a| {
+ // Skip the binary name
+ !a.contains("target/") && *a != "wt"
+ });
+
+ let Some(subcommand) = subcommand else {
+ eprintln!("Usage: wt <command> --help-page");
+ eprintln!("Commands with pages: merge, switch, remove, list");
+ return;
+ };
+
+ // Navigate to the subcommand
+ let sub = cmd.find_subcommand(subcommand);
+ let Some(sub) = sub else {
+ eprintln!("Unknown command: {subcommand}");
+ return;
+ };
+
+ // Get the after_long_help content
+ // Transform ```console to ```bash for Zola compatibility
+ let after_help = sub
+ .get_after_long_help()
+ .map(|s| s.to_string().replace("```console\n", "```bash\n"))
+ .unwrap_or_default();
+
+ // Get the help reference block
+ let filtered_args: Vec<String> = args
+ .iter()
+ .map(|a| {
+ if a == "--help-page" {
+ "--help".to_string()
+ } else {
+ a.clone()
+ }
+ })
+ .collect();
+
+ let mut cmd_for_help = cli::build_command();
+ cmd_for_help = cmd_for_help.color(ColorChoice::Never);
+
+ let help_block = if let Err(err) = cmd_for_help.try_get_matches_from_mut(filtered_args)
+ && matches!(
+ err.kind(),
+ ErrorKind::DisplayHelp | ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
+ ) {
+ err.render()
+ .to_string()
+ .replace("```text\n", "```\n")
+ .replace("```console\n", "```bash\n")
+ } else {
+ String::new()
+ };
+
+ // Split help_block into before and after the after_help section
+ // The help block includes the after_help at the end, we want just the reference part
+ let reference_block = if !after_help.is_empty() {
+ // Find where after_help starts in the help output and take everything before it
+ // The after_help starts after the last option block
+ if let Some(pos) = help_block.find(&after_help[..after_help.len().min(50)]) {
+ help_block[..pos].trim_end().to_string()
+ } else {
+ help_block.clone()
+ }
+ } else {
+ help_block
+ };
+
+ // Title uses "wt <command>" format for consistency
+ let title = format!("wt {subcommand}");
+
+ // Weight mapping (for nav order)
+ // Commands are grouped together after Concepts (weight 3)
+ // Order: switch, list (daily use), merge, remove (workflow completion), then utilities
+ let weight = match subcommand.as_str() {
+ "switch" => 10,
+ "list" => 11,
+ "merge" => 12,
+ "remove" => 13,
+ "select" => 14,
+ "config" => 15,
+ "step" => 16,
+ _ => 50,
+ };
+
+ // Output the page
+ println!("+++");
+ println!("title = \"{title}\"");
+ println!("weight = {weight}");
+ println!();
+ println!("[extra]");
+ println!("group = \"Commands\"");
+ println!("+++");
+ println!();
+ println!("{}", after_help.trim());
+ println!();
+ println!("---");
+ println!();
+ println!("## Command Reference");
+ println!();
+ println!(
+ "<!-- ⚠️ AUTO-GENERATED from `wt {subcommand} --help-page` — edit cli.rs to update -->"
+ );
+ println!();
+ println!("```bash");
+ print!("{}", reference_block.trim());
+ println!();
+ println!("```");
+}
+
/// Enhance clap errors with command-specific hints, then exit.
///
/// For `wt switch` missing the branch argument, adds hints about shortcuts.