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