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