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.mdindex 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.mddeleted file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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.scssindex 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.htmlindex 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.rsindex 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.