Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
refactor: inline user config docs into CLI help (#618)
Maximilian Roosfe12a688fbfe
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.mdindex 22fb6edaf..f42737ed0 100644--- a/.claude-plugin/skills/worktrunk/reference/config.md+++ b/.claude-plugin/skills/worktrunk/reference/config.md@@ -2,13 +2,6 @@Manages configuration, shell integration, and runtime settings.-Worktrunk uses two configuration files:--| File | Location | Purpose |-|------|----------|---------|-| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |-| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |-## ExamplesInstall shell integration (required for directory switching):@@ -35,75 +28,104 @@ Show current configuration and file locations:wt config show```-## User config+## Configuration files++| File | Location | Purpose |+|------|----------|---------|+| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |+| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |++<!-- USER_CONFIG_START -->+# Worktrunk User Configuration-The user config stores personal preferences that apply across all repositories. Create it with `wt config create` and view with `wt config show`.+Create with `wt config create`.-### Worktree path template+Location:-Controls where new worktrees are created. The template is relative to the repository root.+- macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)+- Windows: `%APPDATA%\worktrunk\config.toml`++## Worktree Path Template++Controls where new worktrees are created. Paths are relative to the repository root.++**Variables:**-**Available variables:**- `{{ repo }}` — repository directory name- `{{ branch }}` — raw branch name (e.g., `feature/auth`)-- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`+- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)+- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)-**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:```toml# Default — siblings in parent directory-# Creates: ~/code/myproject.feature-login+# Creates: ~/code/myproject.feature-authworktree-path = "../{{ repo }}.{{ branch | sanitize }}"# Inside the repository-# Creates: ~/code/myproject/.worktrees/feature-login+# Creates: ~/code/myproject/.worktrees/feature-authworktree-path = ".worktrees/{{ branch | sanitize }}"# Namespaced (useful when multiple repos share a parent directory)-# Creates: ~/code/worktrees/myproject/feature-login+# Creates: ~/code/worktrees/myproject/feature-authworktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"# Nested bare repo (git clone --bare <url> project/.git)-# Creates: ~/code/project/feature-login (sibling to .git)+# Creates: ~/code/project/feature-auth (sibling to .git)worktree-path = "../{{ branch | sanitize }}"```-### Command settings+## List Command Defaults-Set persistent flag values for commands. These apply unless explicitly overridden on the command line.--**`wt list`:**+Persistent flag values for `wt list`. Override on command line as needed.```toml[list]-# All off by default-full = true # --full-branches = true # --branches-remotes = true # --remotes+full = false # Show CI status and main…± diffstat columns (--full)+branches = false # Include branches without worktrees (--branches)+remotes = false # Include remote-only branches (--remotes)```-**`wt step commit` and `wt merge` staging:**+## Commit Defaults++Shared by `wt step commit`, `wt step squash`, and `wt merge`.```toml[commit]-stage = "all" # "all" (default), "tracked", or "none"+stage = "all" # What to stage before commit: "all", "tracked", or "none"```-**`wt merge`:**+## Merge Command Defaults++All flags are on by default. Set to false to change default behavior.```toml[merge]-# These flags are on by default; set to false to disable-squash = false # Preserve individual commits (--no-squash)-commit = false # Skip committing uncommitted changes (also disables squash)-rebase = false # Skip rebase (fails if not already rebased)-remove = false # Keep worktree after merge (--no-remove)-verify = false # Skip hooks (--no-verify)+squash = true # Squash commits into one (--no-squash to preserve history)+commit = true # Commit uncommitted changes first (--no-commit to skip)+rebase = true # Rebase onto target before merge (--no-rebase to skip)+remove = true # Remove worktree after merge (--no-remove to keep)+verify = true # Run project hooks (--no-verify to skip)```-### LLM commit messages+## Select Command Defaults-Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):+Pager behavior for `wt select` diff previews.++```toml+[select]+# Pager command with flags for diff preview (overrides git's core.pager)+# Use this to specify pager flags needed for non-TTY contexts+# Example:+# pager = "delta --paging=never"+```++## LLM Commit Messages++Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.++Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):```toml[commit-generation]@@ -111,34 +133,119 @@ command = "llm"args = ["-m", "claude-haiku-4.5"]```-See [LLM Commit Messages](https://worktrunk.dev/llm-commits/) for setup details and template customization.+Using [aichat](https://github.com/sigoden/aichat):++```toml+[commit-generation]+command = "aichat"+args = ["-m", "claude:claude-haiku-4.5"]+```++See [Custom Prompt Templates](#custom-prompt-templates) for inline template options.-### Approved commands+## Approved Commands-When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:+Commands approved for project hooks. Auto-populated when approving hooks on first run, or via `wt hook approvals add`.```toml-[projects."my-project"]+[projects."github.com/user/repo"]approved-commands = ["npm ci", "npm test"]```-Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.++## Custom Prompt Templates++Templates use [minijinja](https://docs.rs/minijinja/) syntax.++### Commit Template-### User hooks+Available variables:-Personal hooks that run for all repositories. Use the same syntax as project hooks:+- `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content+- `{{ branch }}`, `{{ repo }}` — context+- `{{ recent_commits }}` — recent commit messages+Default template:++<!-- DEFAULT_TEMPLATE_START -->```toml-[post-create]-setup = "echo 'Setting up worktree...'"+[commit-generation]+template = """+Write a commit message for the staged changes below.-[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"+<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match recent commit style (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++<context>+Branch: {{ branch }}+{% if recent_commits %}<recent_commits>+{% for commit in recent_commits %}- {{ commit }}+{% endfor %}</recent_commits>{% endif %}+</context>++"""```+<!-- DEFAULT_TEMPLATE_END -->++### Squash Template++Available variables (in addition to commit template variables):-User hooks run before project hooks and don't require approval. Skip with `--no-verify`.+- `{{ commits }}` — list of commits being squashed+- `{{ target_branch }}` — merge target branch-See [`wt hook`](https://worktrunk.dev/hook/#user-hooks) for complete documentation.+Default template:++<!-- DEFAULT_SQUASH_TEMPLATE_START -->+```toml+[commit-generation]+squash-template = """+Combine these commits into a single commit message.++<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match the style of commits being squashed (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<commits branch="{{ branch }}" target="{{ target_branch }}">+{% for commit in commits %}- {{ commit }}+{% endfor %}</commits>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++"""+```+<!-- DEFAULT_SQUASH_TEMPLATE_END -->+<!-- USER_CONFIG_END -->## Project config@@ -290,342 +397,6 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>Show debug info (-v), or also write diagnostic report (-vv)-## wt config create--### User config--Creates `~/.config/worktrunk/config.toml` with the following content:--```-# Worktrunk Global Configuration-# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)-#-# Alternative locations (XDG Base Directory spec):-# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml-# Windows: %APPDATA%\worktrunk\config.toml--# Commit Message Generation (Optional)-# For generating commit messages during merge operations (wt merge)-# [commit-generation]-# Example: Simon Willison's llm CLI (https://github.com/simonw/llm)-# Install: pip install llm llm-anthropic-# command = "llm"-# args = ["-m", "claude-haiku-4.5"]--# Alternative: AIChat - Rust-based, supports 20+ providers-# Install from: https://github.com/sigoden/aichat-# command = "aichat"-# args = ["-m", "claude:claude-haiku-4.5"]--# Optional: Load template from file (mutually exclusive with 'template')-# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt-# template-file = "~/.config/worktrunk/commit-template.txt"--# Optional: Load squash template from file (mutually exclusive with 'squash-template')-# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt-# squash-template-file = "~/.config/worktrunk/squash-template.txt"--# See "Custom Prompt Templates" section at end of file for inline template options.--# Worktree Path Template-# Variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Raw branch name (e.g., "feature/auth")-# {{ branch | sanitize }} - Filesystem-safe: / and \ replaced by - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe: lowercase, underscores, hash suffix (e.g., "feature_auth_x7k")-#-# Paths are relative to the main worktree root (original repository directory).-#-# Example paths created (repo at /Users/dev/myproject, branch feature/auth):-# "../{{ repo }}.{{ branch | sanitize }}" → /Users/dev/myproject.feature-auth-# ".worktrees/{{ branch | sanitize }}" → /Users/dev/myproject/.worktrees/feature-auth-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"--# Alternative: Inside repo (useful for bare repos)-# worktree-path = ".worktrees/{{ branch | sanitize }}"--# List Command Defaults-# Configure default behavior for `wt list`-[list]-full = false # Show CI and default-branch merge-base diffstat (`main…±` column) by default-branches = false # Include branches without worktrees by default-remotes = false # Include remote branches by default-timeout-ms = 0 # (Experimental) Per-task timeout in ms; 0 = no timeout; --full disables--# Commit Defaults (shared by `wt step commit`, `wt step squash`, and `wt merge`)-[commit]-stage = "all" # What to stage: "all", "tracked", or "none"--# Merge Command Defaults-# Note: `stage` defaults from [commit] section above-[merge]-squash = true # Squash commits when merging-commit = true # Commit uncommitted changes during merge (disables squash when false)-rebase = true # Rebase onto target before merging-remove = true # Remove worktree after merge-verify = true # Run project hooks--# Select Command Defaults-# Configure pager behavior for `wt select` diff previews-[select]-# Pager command with flags for diff preview (overrides git's core.pager)-# Use this to specify pager flags needed for non-TTY contexts-# Example: pager = "delta --paging=never"--# Approved Commands-# Commands approved for project hooks in this repo-# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`-[projects."github.com/user/repo"]-approved-commands = ["npm ci", "npm test"]--# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),-# use a separate PROJECT config file at <repo>/.config/wt.toml-# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/--# ============================================================================-# Custom Prompt Templates (Advanced)-# ============================================================================-# These options belong under [commit-generation] section above.-# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`--# Optional: Custom prompt template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}-# If not specified, uses the default template shown below:-# <!-- DEFAULT_TEMPLATE_START -->-# template = """-# Write a commit message for the staged changes below.-#-# <format>-# - Subject under 50 chars, blank line, then optional body-# - Output only the commit message, no quotes or code blocks-# </format>-#-# <style>-# - Imperative mood: "Add feature" not "Added feature"-# - Match recent commit style (conventional commits if used)-# - Describe the change, not the intent or benefit-# </style>-#-# <diffstat>-# {{ git_diff_stat }}-# </diffstat>-#-# <diff>-# {{ git_diff }}-# </diff>-#-# <context>-# Branch: {{ branch }}-# {% if recent_commits %}<recent_commits>-# {% for commit in recent_commits %}- {{ commit }}-# {% endfor %}</recent_commits>{% endif %}-# </context>-# """-# <!-- DEFAULT_TEMPLATE_END -->-#-# Example alternative template with different style:-# template = """-# Generate a commit message for {{ repo | upper }}.-#-# Branch: {{ branch }}-# {%- if recent_commits %}-#-# Recent commit style ({{ recent_commits | length }} commits):-# {%- for commit in recent_commits %}-# {{ loop.index }}. {{ commit }}-# {%- endfor %}-# {%- endif %}-#-# Changes to commit:-# ```-# {{ git_diff }}-# ```-#-# Requirements:-# - Follow the style of recent commits above-# - First line under 50 chars-# - Focus on WHY, not HOW-# """--# Optional: Custom squash commit message template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}, {{ commits }}, {{ target_branch }}-# If not specified, uses the default template:-# <!-- DEFAULT_SQUASH_TEMPLATE_START -->-# squash-template = """-# Combine these commits into a single commit message.-#-# <format>-# - Subject under 50 chars, blank line, then optional body-# - Output only the commit message, no quotes or code blocks-# </format>-#-# <style>-# - Imperative mood: "Add feature" not "Added feature"-# - Match the style of commits being squashed (conventional commits if used)-# - Describe the change, not the intent or benefit-# </style>-#-# <commits branch="{{ branch }}" target="{{ target_branch }}">-# {% for commit in commits %}- {{ commit }}-# {% endfor %}</commits>-#-# <diffstat>-# {{ git_diff_stat }}-# </diffstat>-#-# <diff>-# {{ git_diff }}-# </diff>-# """-# <!-- DEFAULT_SQUASH_TEMPLATE_END -->-#-# Example alternative template:-# squash-template = """-# Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.-#-# {% if commits | length > 1 -%}-# Commits being combined:-# {%- for c in commits %}-# {{ loop.index }}/{{ loop.length }}: {{ c }}-# {%- endfor %}-# {%- else -%}-# Single commit: {{ commits[0] }}-# {%- endif %}-#-# Generate one cohesive commit message that captures the overall change.-# Use conventional commit format (feat/fix/docs/refactor).-# """-```--### Project config--With `--project`, creates `.config/wt.toml` in the current repository:--```-# Worktrunk Project Configuration-# Copy to: <repo>/.config/wt.toml-#-# Project-specific hooks that run automatically during worktree operations.-# Check this file into git to share hooks across all developers.--# ============================================================================-# Hook Formats-# ============================================================================-# All hooks support two formats:-#-# Single command:-# post-create = "npm install"-#-# Named table (multiple commands):-# [post-create]-# deps = "npm install"-# build = "npm run build"-#-# Named commands appear in output, making it easier to identify failures.--# ============================================================================-# Template Variables — see https://worktrunk.dev/hook/#template-variables-# ============================================================================-# Common variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Branch name (e.g., "feature/auth")-# {{ worktree_path }} - Absolute path to worktree-# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)-# {{ default_branch }} - Default branch name (e.g., "main")-# {{ target }} - Target branch (merge hooks only)-#-# Filters:-# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")-# {{ branch | hash_port }} - Deterministic port 10000-19999--# ============================================================================-# Hooks-# ============================================================================--# Post-Create: Runs after worktree creation, BLOCKS until complete-# Use for: installing dependencies, setting up databases, copying configs-#-# [post-create]-# deps = "npm ci"-# env = "cp .env.example .env"--# Post-Start: Runs in BACKGROUND after worktree creation (parallel)-# Use for: dev servers, file watchers, background builds-# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log-#-# [post-start]-# server = "npm run dev -- --port {{ branch | hash_port }}"-# watch = "npm run watch"--# Post-Switch: Runs in BACKGROUND after every switch (parallel)-# Use for: terminal tab naming, tmux window titles, IDE notifications-#-# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"--# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)-# Use for: formatters, linters, quick checks-#-# [pre-commit]-# format = "npm run format:check"-# lint = "npm run lint"--# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)-# Use for: tests, build verification-#-# [pre-merge]-# test = "npm test"-# build = "npm run build"--# Post-Merge: Runs after successful merge, BLOCKS-# Use for: deployment, notifications-#-# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"--# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)-# Use for: cleanup, stopping services-#-# pre-remove = "docker compose down"--# ============================================================================-# Dev Server URL (shown in `wt list`)-# ============================================================================-# [list]-# url = "http://localhost:{{ branch | hash_port }}"--# ============================================================================-# CI Platform Override-# ============================================================================-# Override CI platform detection for GitHub Enterprise or self-hosted GitLab-# with custom domains where URL detection fails.-#-# [ci]-# platform = "github" # or "gitlab"-```--### Command reference--wt config create - Create configuration file--Usage: <b><span class=c>wt config create</span></b> <span class=c>[OPTIONS]</span>--<b><span class=g>Options:</span></b>- <b><span class=c>--project</span></b>- Create project config (<b>.config/wt.toml</b>) instead of user config-- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>- Working directory for this command-- <b><span class=c>--config</span></b><span class=c> <path></span>- User config file path-- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>- Show debug info (-v), or also write diagnostic report (-vv)-## wt config showShows location and contents of user config (`~/.config/worktrunk/config.toml`)diff --git a/dev/config.example.toml b/dev/config.example.tomlindex 1d876aa24..6c02cd73a 100644--- a/dev/config.example.toml+++ b/dev/config.example.toml@@ -1,98 +1,121 @@-# Worktrunk Global Configuration-# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)-#-# Alternative locations (XDG Base Directory spec):-# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml-# Windows: %APPDATA%\worktrunk\config.toml--# Commit Message Generation (Optional)-# For generating commit messages during merge operations (wt merge)+# # Worktrunk User Configuration+#+# Create with `wt config create`.+#+# Location:+#+# - macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)+# - Windows: `%APPDATA%\worktrunk\config.toml`+#+# ## Worktree Path Template+#+# Controls where new worktrees are created. Paths are relative to the repository root.+#+# **Variables:**+#+# - `{{ repo }}` — repository directory name+# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)+# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)+# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)+#+# **Examples** for repo at `~/code/myproject`, branch `feature/auth`:+#+# # Default — siblings in parent directory+# # Creates: ~/code/myproject.feature-auth+# worktree-path = "../{{ repo }}.{{ branch | sanitize }}"+#+# # Inside the repository+# # Creates: ~/code/myproject/.worktrees/feature-auth+# worktree-path = ".worktrees/{{ branch | sanitize }}"+#+# # Namespaced (useful when multiple repos share a parent directory)+# # Creates: ~/code/worktrees/myproject/feature-auth+# worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"+#+# # Nested bare repo (git clone --bare <url> project/.git)+# # Creates: ~/code/project/feature-auth (sibling to .git)+# worktree-path = "../{{ branch | sanitize }}"+#+# ## List Command Defaults+#+# Persistent flag values for `wt list`. Override on command line as needed.+#+# [list]+# full = false # Show CI status and main…± diffstat columns (--full)+# branches = false # Include branches without worktrees (--branches)+# remotes = false # Include remote-only branches (--remotes)+#+# ## Commit Defaults+#+# Shared by `wt step commit`, `wt step squash`, and `wt merge`.+#+# [commit]+# stage = "all" # What to stage before commit: "all", "tracked", or "none"+#+# ## Merge Command Defaults+#+# All flags are on by default. Set to false to change default behavior.+#+# [merge]+# squash = true # Squash commits into one (--no-squash to preserve history)+# commit = true # Commit uncommitted changes first (--no-commit to skip)+# rebase = true # Rebase onto target before merge (--no-rebase to skip)+# remove = true # Remove worktree after merge (--no-remove to keep)+# verify = true # Run project hooks (--no-verify to skip)+#+# ## Select Command Defaults+#+# Pager behavior for `wt select` diff previews.+#+# [select]+# # Pager command with flags for diff preview (overrides git's core.pager)+# # Use this to specify pager flags needed for non-TTY contexts+# # Example:+# # pager = "delta --paging=never"+#+# ## LLM Commit Messages+#+# Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.+#+# Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):+## [commit-generation]-# Example: Simon Willison's llm CLI (https://github.com/simonw/llm)-# Install: pip install llm llm-anthropic# command = "llm"# args = ["-m", "claude-haiku-4.5"]--# Alternative: AIChat - Rust-based, supports 20+ providers-# Install from: https://github.com/sigoden/aichat+#+# Using [aichat](https://github.com/sigoden/aichat):+#+# [commit-generation]# command = "aichat"# args = ["-m", "claude:claude-haiku-4.5"]--# Optional: Load template from file (mutually exclusive with 'template')-# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt-# template-file = "~/.config/worktrunk/commit-template.txt"--# Optional: Load squash template from file (mutually exclusive with 'squash-template')-# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt-# squash-template-file = "~/.config/worktrunk/squash-template.txt"--# See "Custom Prompt Templates" section at end of file for inline template options.--# Worktree Path Template-# Variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Raw branch name (e.g., "feature/auth")-# {{ branch | sanitize }} - Filesystem-safe: / and \ replaced by - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe: lowercase, underscores, hash suffix (e.g., "feature_auth_x7k")-#-# Paths are relative to the main worktree root (original repository directory).-#-# Example paths created (repo at /Users/dev/myproject, branch feature/auth):-# "../{{ repo }}.{{ branch | sanitize }}" → /Users/dev/myproject.feature-auth-# ".worktrees/{{ branch | sanitize }}" → /Users/dev/myproject/.worktrees/feature-auth-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"--# Alternative: Inside repo (useful for bare repos)-# worktree-path = ".worktrees/{{ branch | sanitize }}"--# List Command Defaults-# Configure default behavior for `wt list`-[list]-full = false # Show CI and default-branch merge-base diffstat (`main…±` column) by default-branches = false # Include branches without worktrees by default-remotes = false # Include remote branches by default-timeout-ms = 0 # (Experimental) Per-task timeout in ms; 0 = no timeout; --full disables--# Commit Defaults (shared by `wt step commit`, `wt step squash`, and `wt merge`)-[commit]-stage = "all" # What to stage: "all", "tracked", or "none"--# Merge Command Defaults-# Note: `stage` defaults from [commit] section above-[merge]-squash = true # Squash commits when merging-commit = true # Commit uncommitted changes during merge (disables squash when false)-rebase = true # Rebase onto target before merging-remove = true # Remove worktree after merge-verify = true # Run project hooks--# Select Command Defaults-# Configure pager behavior for `wt select` diff previews-[select]-# Pager command with flags for diff preview (overrides git's core.pager)-# Use this to specify pager flags needed for non-TTY contexts-# Example: pager = "delta --paging=never"--# Approved Commands-# Commands approved for project hooks in this repo-# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`-[projects."github.com/user/repo"]-approved-commands = ["npm ci", "npm test"]--# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),-# use a separate PROJECT config file at <repo>/.config/wt.toml-# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/--# ============================================================================-# Custom Prompt Templates (Advanced)-# ============================================================================-# These options belong under [commit-generation] section above.-# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`--# Optional: Custom prompt template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}-# If not specified, uses the default template shown below:+#+# See [Custom Prompt Templates](#custom-prompt-templates) for inline template options.+#+# ## Approved Commands+#+# Commands approved for project hooks. Auto-populated when approving hooks on first run, or via `wt hook approvals add`.+#+# [projects."github.com/user/repo"]+# approved-commands = ["npm ci", "npm test"]+#+# For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.+#+# ## Custom Prompt Templates+#+# Templates use [minijinja](https://docs.rs/minijinja/) syntax.+#+# ### Commit Template+#+# Available variables:+#+# - `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content+# - `{{ branch }}`, `{{ repo }}` — context+# - `{{ recent_commits }}` — recent commit messages+#+# Default template:+## <!-- DEFAULT_TEMPLATE_START -->+# [commit-generation]# template = """# Write a commit message for the staged changes below.#@@ -121,37 +144,21 @@ approved-commands = ["npm ci", "npm test"]# {% for commit in recent_commits %}- {{ commit }}# {% endfor %}</recent_commits>{% endif %}# </context>+## """# <!-- DEFAULT_TEMPLATE_END -->#-# Example alternative template with different style:-# template = """-# Generate a commit message for {{ repo | upper }}.+# ### Squash Template#-# Branch: {{ branch }}-# {%- if recent_commits %}+# Available variables (in addition to commit template variables):#-# Recent commit style ({{ recent_commits | length }} commits):-# {%- for commit in recent_commits %}-# {{ loop.index }}. {{ commit }}-# {%- endfor %}-# {%- endif %}+# - `{{ commits }}` — list of commits being squashed+# - `{{ target_branch }}` — merge target branch#-# Changes to commit:-# ```-# {{ git_diff }}-# ```+# Default template:#-# Requirements:-# - Follow the style of recent commits above-# - First line under 50 chars-# - Focus on WHY, not HOW-# """--# Optional: Custom squash commit message template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}, {{ commits }}, {{ target_branch }}-# If not specified, uses the default template:# <!-- DEFAULT_SQUASH_TEMPLATE_START -->+# [commit-generation]# squash-template = """# Combine these commits into a single commit message.#@@ -177,22 +184,6 @@ approved-commands = ["npm ci", "npm test"]# <diff># {{ git_diff }}# </diff>-# """-# <!-- DEFAULT_SQUASH_TEMPLATE_END -->#-# Example alternative template:-# squash-template = """-# Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.-#-# {% if commits | length > 1 -%}-# Commits being combined:-# {%- for c in commits %}-# {{ loop.index }}/{{ loop.length }}: {{ c }}-# {%- endfor %}-# {%- else -%}-# Single commit: {{ commits[0] }}-# {%- endif %}-#-# Generate one cohesive commit message that captures the overall change.-# Use conventional commit format (feat/fix/docs/refactor).# """+# <!-- DEFAULT_SQUASH_TEMPLATE_END -->diff --git a/docs/content/config.md b/docs/content/config.mdindex 9d7233461..03b2057f6 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -10,13 +10,6 @@ group = "Commands"Manages configuration, shell integration, and runtime settings.-Worktrunk uses two configuration files:--| File | Location | Purpose |-|------|----------|---------|-| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |-| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |-## ExamplesInstall shell integration (required for directory switching):@@ -43,75 +36,104 @@ Show current configuration and file locations:wt config show```-## User config+## Configuration files++| File | Location | Purpose |+|------|----------|---------|+| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |+| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |++<!-- USER_CONFIG_START -->+# Worktrunk User Configuration-The user config stores personal preferences that apply across all repositories. Create it with `wt config create` and view with `wt config show`.+Create with `wt config create`.-### Worktree path template+Location:-Controls where new worktrees are created. The template is relative to the repository root.+- macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)+- Windows: `%APPDATA%\worktrunk\config.toml`++## Worktree Path Template++Controls where new worktrees are created. Paths are relative to the repository root.++**Variables:**-**Available variables:**- `{{ repo }}` — repository directory name- `{{ branch }}` — raw branch name (e.g., `feature/auth`)-- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`+- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)+- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)-**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:```toml# Default — siblings in parent directory-# Creates: ~/code/myproject.feature-login+# Creates: ~/code/myproject.feature-authworktree-path = "../{{ repo }}.{{ branch | sanitize }}"# Inside the repository-# Creates: ~/code/myproject/.worktrees/feature-login+# Creates: ~/code/myproject/.worktrees/feature-authworktree-path = ".worktrees/{{ branch | sanitize }}"# Namespaced (useful when multiple repos share a parent directory)-# Creates: ~/code/worktrees/myproject/feature-login+# Creates: ~/code/worktrees/myproject/feature-authworktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"# Nested bare repo (git clone --bare <url> project/.git)-# Creates: ~/code/project/feature-login (sibling to .git)+# Creates: ~/code/project/feature-auth (sibling to .git)worktree-path = "../{{ branch | sanitize }}"```-### Command settings+## List Command Defaults-Set persistent flag values for commands. These apply unless explicitly overridden on the command line.--**`wt list`:**+Persistent flag values for `wt list`. Override on command line as needed.```toml[list]-# All off by default-full = true # --full-branches = true # --branches-remotes = true # --remotes+full = false # Show CI status and main…± diffstat columns (--full)+branches = false # Include branches without worktrees (--branches)+remotes = false # Include remote-only branches (--remotes)```-**`wt step commit` and `wt merge` staging:**+## Commit Defaults++Shared by `wt step commit`, `wt step squash`, and `wt merge`.```toml[commit]-stage = "all" # "all" (default), "tracked", or "none"+stage = "all" # What to stage before commit: "all", "tracked", or "none"```-**`wt merge`:**+## Merge Command Defaults++All flags are on by default. Set to false to change default behavior.```toml[merge]-# These flags are on by default; set to false to disable-squash = false # Preserve individual commits (--no-squash)-commit = false # Skip committing uncommitted changes (also disables squash)-rebase = false # Skip rebase (fails if not already rebased)-remove = false # Keep worktree after merge (--no-remove)-verify = false # Skip hooks (--no-verify)+squash = true # Squash commits into one (--no-squash to preserve history)+commit = true # Commit uncommitted changes first (--no-commit to skip)+rebase = true # Rebase onto target before merge (--no-rebase to skip)+remove = true # Remove worktree after merge (--no-remove to keep)+verify = true # Run project hooks (--no-verify to skip)+```++## Select Command Defaults++Pager behavior for `wt select` diff previews.++```toml+[select]+# Pager command with flags for diff preview (overrides git's core.pager)+# Use this to specify pager flags needed for non-TTY contexts+# Example:+# pager = "delta --paging=never"```-### LLM commit messages+## LLM Commit Messages++Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.-Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):+Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):```toml[commit-generation]@@ -119,34 +141,119 @@ command = "llm"args = ["-m", "claude-haiku-4.5"]```-See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.+Using [aichat](https://github.com/sigoden/aichat):++```toml+[commit-generation]+command = "aichat"+args = ["-m", "claude:claude-haiku-4.5"]+```++See [Custom Prompt Templates](#custom-prompt-templates) for inline template options.-### Approved commands+## Approved Commands-When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:+Commands approved for project hooks. Auto-populated when approving hooks on first run, or via `wt hook approvals add`.```toml-[projects."my-project"]+[projects."github.com/user/repo"]approved-commands = ["npm ci", "npm test"]```-Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.++## Custom Prompt Templates++Templates use [minijinja](https://docs.rs/minijinja/) syntax.++### Commit Template-### User hooks+Available variables:-Personal hooks that run for all repositories. Use the same syntax as project hooks:+- `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content+- `{{ branch }}`, `{{ repo }}` — context+- `{{ recent_commits }}` — recent commit messages+Default template:++<!-- DEFAULT_TEMPLATE_START -->```toml-[post-create]-setup = "echo 'Setting up worktree...'"+[commit-generation]+template = """+Write a commit message for the staged changes below.-[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"+<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match recent commit style (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++<context>+Branch: {{ branch }}+{% if recent_commits %}<recent_commits>+{% for commit in recent_commits %}- {{ commit }}+{% endfor %}</recent_commits>{% endif %}+</context>++"""```+<!-- DEFAULT_TEMPLATE_END -->++### Squash Template++Available variables (in addition to commit template variables):++- `{{ commits }}` — list of commits being squashed+- `{{ target_branch }}` — merge target branch-User hooks run before project hooks and don't require approval. Skip with `--no-verify`.+Default template:-See [`wt hook`](@/hook.md#user-hooks) for complete documentation.+<!-- DEFAULT_SQUASH_TEMPLATE_START -->+```toml+[commit-generation]+squash-template = """+Combine these commits into a single commit message.++<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match the style of commits being squashed (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<commits branch="{{ branch }}" target="{{ target_branch }}">+{% for commit in commits %}- {{ commit }}+{% endfor %}</commits>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++"""+```+<!-- DEFAULT_SQUASH_TEMPLATE_END -->+<!-- USER_CONFIG_END -->## Project config@@ -300,345 +407,6 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spaShow debug info (-v), or also write diagnostic report (-vv){% end %}-## wt config create--### User config--Creates `~/.config/worktrunk/config.toml` with the following content:--```-# Worktrunk Global Configuration-# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)-#-# Alternative locations (XDG Base Directory spec):-# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml-# Windows: %APPDATA%\worktrunk\config.toml--# Commit Message Generation (Optional)-# For generating commit messages during merge operations (wt merge)-# [commit-generation]-# Example: Simon Willison's llm CLI (https://github.com/simonw/llm)-# Install: pip install llm llm-anthropic-# command = "llm"-# args = ["-m", "claude-haiku-4.5"]--# Alternative: AIChat - Rust-based, supports 20+ providers-# Install from: https://github.com/sigoden/aichat-# command = "aichat"-# args = ["-m", "claude:claude-haiku-4.5"]--# Optional: Load template from file (mutually exclusive with 'template')-# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt-# template-file = "~/.config/worktrunk/commit-template.txt"--# Optional: Load squash template from file (mutually exclusive with 'squash-template')-# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt-# squash-template-file = "~/.config/worktrunk/squash-template.txt"--# See "Custom Prompt Templates" section at end of file for inline template options.--# Worktree Path Template-# Variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Raw branch name (e.g., "feature/auth")-# {{ branch | sanitize }} - Filesystem-safe: / and \ replaced by - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe: lowercase, underscores, hash suffix (e.g., "feature_auth_x7k")-#-# Paths are relative to the main worktree root (original repository directory).-#-# Example paths created (repo at /Users/dev/myproject, branch feature/auth):-# "../{{ repo }}.{{ branch | sanitize }}" → /Users/dev/myproject.feature-auth-# ".worktrees/{{ branch | sanitize }}" → /Users/dev/myproject/.worktrees/feature-auth-worktree-path = "../{{ repo }}.{{ branch | sanitize }}"--# Alternative: Inside repo (useful for bare repos)-# worktree-path = ".worktrees/{{ branch | sanitize }}"--# List Command Defaults-# Configure default behavior for `wt list`-[list]-full = false # Show CI and default-branch merge-base diffstat (`main…±` column) by default-branches = false # Include branches without worktrees by default-remotes = false # Include remote branches by default-timeout-ms = 0 # (Experimental) Per-task timeout in ms; 0 = no timeout; --full disables--# Commit Defaults (shared by `wt step commit`, `wt step squash`, and `wt merge`)-[commit]-stage = "all" # What to stage: "all", "tracked", or "none"--# Merge Command Defaults-# Note: `stage` defaults from [commit] section above-[merge]-squash = true # Squash commits when merging-commit = true # Commit uncommitted changes during merge (disables squash when false)-rebase = true # Rebase onto target before merging-remove = true # Remove worktree after merge-verify = true # Run project hooks--# Select Command Defaults-# Configure pager behavior for `wt select` diff previews-[select]-# Pager command with flags for diff preview (overrides git's core.pager)-# Use this to specify pager flags needed for non-TTY contexts-# Example: pager = "delta --paging=never"--# Approved Commands-# Commands approved for project hooks in this repo-# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`-[projects."github.com/user/repo"]-approved-commands = ["npm ci", "npm test"]--# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),-# use a separate PROJECT config file at <repo>/.config/wt.toml-# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/--# ============================================================================-# Custom Prompt Templates (Advanced)-# ============================================================================-# These options belong under [commit-generation] section above.-# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`--# Optional: Custom prompt template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}-# If not specified, uses the default template shown below:-# <!-- DEFAULT_TEMPLATE_START -->-# template = """-# Write a commit message for the staged changes below.-#-# <format>-# - Subject under 50 chars, blank line, then optional body-# - Output only the commit message, no quotes or code blocks-# </format>-#-# <style>-# - Imperative mood: "Add feature" not "Added feature"-# - Match recent commit style (conventional commits if used)-# - Describe the change, not the intent or benefit-# </style>-#-# <diffstat>-# {{ git_diff_stat }}-# </diffstat>-#-# <diff>-# {{ git_diff }}-# </diff>-#-# <context>-# Branch: {{ branch }}-# {% if recent_commits %}<recent_commits>-# {% for commit in recent_commits %}- {{ commit }}-# {% endfor %}</recent_commits>{% endif %}-# </context>-# """-# <!-- DEFAULT_TEMPLATE_END -->-#-# Example alternative template with different style:-# template = """-# Generate a commit message for {{ repo | upper }}.-#-# Branch: {{ branch }}-# {%- if recent_commits %}-#-# Recent commit style ({{ recent_commits | length }} commits):-# {%- for commit in recent_commits %}-# {{ loop.index }}. {{ commit }}-# {%- endfor %}-# {%- endif %}-#-# Changes to commit:-# ```-# {{ git_diff }}-# ```-#-# Requirements:-# - Follow the style of recent commits above-# - First line under 50 chars-# - Focus on WHY, not HOW-# """--# Optional: Custom squash commit message template (inline) - Uses minijinja syntax-# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}, {{ commits }}, {{ target_branch }}-# If not specified, uses the default template:-# <!-- DEFAULT_SQUASH_TEMPLATE_START -->-# squash-template = """-# Combine these commits into a single commit message.-#-# <format>-# - Subject under 50 chars, blank line, then optional body-# - Output only the commit message, no quotes or code blocks-# </format>-#-# <style>-# - Imperative mood: "Add feature" not "Added feature"-# - Match the style of commits being squashed (conventional commits if used)-# - Describe the change, not the intent or benefit-# </style>-#-# <commits branch="{{ branch }}" target="{{ target_branch }}">-# {% for commit in commits %}- {{ commit }}-# {% endfor %}</commits>-#-# <diffstat>-# {{ git_diff_stat }}-# </diffstat>-#-# <diff>-# {{ git_diff }}-# </diff>-# """-# <!-- DEFAULT_SQUASH_TEMPLATE_END -->-#-# Example alternative template:-# squash-template = """-# Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.-#-# {% if commits | length > 1 -%}-# Commits being combined:-# {%- for c in commits %}-# {{ loop.index }}/{{ loop.length }}: {{ c }}-# {%- endfor %}-# {%- else -%}-# Single commit: {{ commits[0] }}-# {%- endif %}-#-# Generate one cohesive commit message that captures the overall change.-# Use conventional commit format (feat/fix/docs/refactor).-# """-```--### Project config--With `--project`, creates `.config/wt.toml` in the current repository:--```-# Worktrunk Project Configuration-# Copy to: <repo>/.config/wt.toml-#-# Project-specific hooks that run automatically during worktree operations.-# Check this file into git to share hooks across all developers.--# ============================================================================-# Hook Formats-# ============================================================================-# All hooks support two formats:-#-# Single command:-# post-create = "npm install"-#-# Named table (multiple commands):-# [post-create]-# deps = "npm install"-# build = "npm run build"-#-# Named commands appear in output, making it easier to identify failures.--# ============================================================================-# Template Variables — see https://worktrunk.dev/hook/#template-variables-# ============================================================================-# Common variables:-# {{ repo }} - Repository directory name (e.g., "myproject")-# {{ branch }} - Branch name (e.g., "feature/auth")-# {{ worktree_path }} - Absolute path to worktree-# {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)-# {{ default_branch }} - Default branch name (e.g., "main")-# {{ target }} - Target branch (merge hooks only)-#-# Filters:-# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")-# {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")-# {{ branch | hash_port }} - Deterministic port 10000-19999--# ============================================================================-# Hooks-# ============================================================================--# Post-Create: Runs after worktree creation, BLOCKS until complete-# Use for: installing dependencies, setting up databases, copying configs-#-# [post-create]-# deps = "npm ci"-# env = "cp .env.example .env"--# Post-Start: Runs in BACKGROUND after worktree creation (parallel)-# Use for: dev servers, file watchers, background builds-# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log-#-# [post-start]-# server = "npm run dev -- --port {{ branch | hash_port }}"-# watch = "npm run watch"--# Post-Switch: Runs in BACKGROUND after every switch (parallel)-# Use for: terminal tab naming, tmux window titles, IDE notifications-#-# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"--# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)-# Use for: formatters, linters, quick checks-#-# [pre-commit]-# format = "npm run format:check"-# lint = "npm run lint"--# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)-# Use for: tests, build verification-#-# [pre-merge]-# test = "npm test"-# build = "npm run build"--# Post-Merge: Runs after successful merge, BLOCKS-# Use for: deployment, notifications-#-# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"--# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)-# Use for: cleanup, stopping services-#-# pre-remove = "docker compose down"--# ============================================================================-# Dev Server URL (shown in `wt list`)-# ============================================================================-# [list]-# url = "http://localhost:{{ branch | hash_port }}"--# ============================================================================-# CI Platform Override-# ============================================================================-# Override CI platform detection for GitHub Enterprise or self-hosted GitLab-# with custom domains where URL detection fails.-#-# [ci]-# platform = "github" # or "gitlab"-```--### Command reference--{% terminal() %}-wt config create - Create configuration file--Usage: <b><span class=c>wt config create</span></b> <span class=c>[OPTIONS]</span>--<b><span class=g>Options:</span></b>- <b><span class=c>--project</span></b>- Create project config (<b>.config/wt.toml</b>) instead of user config-- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>- Print help (see a summary with '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>- Working directory for this command-- <b><span class=c>--config</span></b><span class=c> <path></span>- User config file path-- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>- Show debug info (-v), or also write diagnostic report (-vv)-{% end %}--## wt config showShows location and contents of user config (`~/.config/worktrunk/config.toml`)diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 9f4281fb9..fab265413 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1467,14 +1467,7 @@ fi/// Manage configuration and shell integration#[command(- after_long_help = r#"Manages configuration, shell integration, and runtime settings.--Worktrunk uses two configuration files:--| File | Location | Purpose |-|------|----------|---------|-| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |-| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |+ after_long_help = concat!(r#"Manages configuration, shell integration, and runtime settings.## Examples@@ -1502,75 +1495,104 @@ Show current configuration and file locations:wt config show```-## User config+## Configuration files++| File | Location | Purpose |+|------|----------|---------|+| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |+| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |++<!-- USER_CONFIG_START -->+# Worktrunk User Configuration++Create with `wt config create`.++Location:-The user config stores personal preferences that apply across all repositories. Create it with `wt config create` and view with `wt config show`.+- macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)+- Windows: `%APPDATA%\worktrunk\config.toml`-### Worktree path template+## Worktree Path Template-Controls where new worktrees are created. The template is relative to the repository root.+Controls where new worktrees are created. Paths are relative to the repository root.++**Variables:**-**Available variables:**- `{{ repo }}` — repository directory name- `{{ branch }}` — raw branch name (e.g., `feature/auth`)-- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`+- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)+- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)-**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:```toml# Default — siblings in parent directory-# Creates: ~/code/myproject.feature-login+# Creates: ~/code/myproject.feature-authworktree-path = "../{{ repo }}.{{ branch | sanitize }}"# Inside the repository-# Creates: ~/code/myproject/.worktrees/feature-login+# Creates: ~/code/myproject/.worktrees/feature-authworktree-path = ".worktrees/{{ branch | sanitize }}"# Namespaced (useful when multiple repos share a parent directory)-# Creates: ~/code/worktrees/myproject/feature-login+# Creates: ~/code/worktrees/myproject/feature-authworktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"# Nested bare repo (git clone --bare <url> project/.git)-# Creates: ~/code/project/feature-login (sibling to .git)+# Creates: ~/code/project/feature-auth (sibling to .git)worktree-path = "../{{ branch | sanitize }}"```-### Command settings--Set persistent flag values for commands. These apply unless explicitly overridden on the command line.+## List Command Defaults-**`wt list`:**+Persistent flag values for `wt list`. Override on command line as needed.```toml[list]-# All off by default-full = true # --full-branches = true # --branches-remotes = true # --remotes+full = false # Show CI status and main…± diffstat columns (--full)+branches = false # Include branches without worktrees (--branches)+remotes = false # Include remote-only branches (--remotes)```-**`wt step commit` and `wt merge` staging:**+## Commit Defaults++Shared by `wt step commit`, `wt step squash`, and `wt merge`.```toml[commit]-stage = "all" # "all" (default), "tracked", or "none"+stage = "all" # What to stage before commit: "all", "tracked", or "none"```-**`wt merge`:**+## Merge Command Defaults++All flags are on by default. Set to false to change default behavior.```toml[merge]-# These flags are on by default; set to false to disable-squash = false # Preserve individual commits (--no-squash)-commit = false # Skip committing uncommitted changes (also disables squash)-rebase = false # Skip rebase (fails if not already rebased)-remove = false # Keep worktree after merge (--no-remove)-verify = false # Skip hooks (--no-verify)+squash = true # Squash commits into one (--no-squash to preserve history)+commit = true # Commit uncommitted changes first (--no-commit to skip)+rebase = true # Rebase onto target before merge (--no-rebase to skip)+remove = true # Remove worktree after merge (--no-remove to keep)+verify = true # Run project hooks (--no-verify to skip)+```++## Select Command Defaults++Pager behavior for `wt select` diff previews.++```toml+[select]+# Pager command with flags for diff preview (overrides git's core.pager)+# Use this to specify pager flags needed for non-TTY contexts+# Example:+# pager = "delta --paging=never"```-### LLM commit messages+## LLM Commit Messages++Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.-Configure automatic commit message generation. Requires an external tool like [llm](https://llm.datasette.io/):+Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):```toml[commit-generation]@@ -1578,34 +1600,119 @@ command = "llm"args = ["-m", "claude-haiku-4.5"]```-See [LLM Commit Messages](@/llm-commits.md) for setup details and template customization.+Using [aichat](https://github.com/sigoden/aichat):-### Approved commands+```toml+[commit-generation]+command = "aichat"+args = ["-m", "claude:claude-haiku-4.5"]+```-When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:+See [Custom Prompt Templates](#custom-prompt-templates) for inline template options.++## Approved Commands++Commands approved for project hooks. Auto-populated when approving hooks on first run, or via `wt hook approvals add`.```toml-[projects."my-project"]+[projects."github.com/user/repo"]approved-commands = ["npm ci", "npm test"]```-Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.++## Custom Prompt Templates++Templates use [minijinja](https://docs.rs/minijinja/) syntax.-### User hooks+### Commit Template-Personal hooks that run for all repositories. Use the same syntax as project hooks:+Available variables:+- `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content+- `{{ branch }}`, `{{ repo }}` — context+- `{{ recent_commits }}` — recent commit messages++Default template:++<!-- DEFAULT_TEMPLATE_START -->```toml-[post-create]-setup = "echo 'Setting up worktree...'"+[commit-generation]+template = """+Write a commit message for the staged changes below.++<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match recent commit style (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++<context>+Branch: {{ branch }}+{% if recent_commits %}<recent_commits>+{% for commit in recent_commits %}- {{ commit }}+{% endfor %}</recent_commits>{% endif %}+</context>-[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"+"""```+<!-- DEFAULT_TEMPLATE_END -->++### Squash Template++Available variables (in addition to commit template variables):-User hooks run before project hooks and don't require approval. Skip with `--no-verify`.+- `{{ commits }}` — list of commits being squashed+- `{{ target_branch }}` — merge target branch-See [`wt hook`](@/hook.md#user-hooks) for complete documentation.+Default template:++<!-- DEFAULT_SQUASH_TEMPLATE_START -->+```toml+[commit-generation]+squash-template = """+Combine these commits into a single commit message.++<format>+- Subject under 50 chars, blank line, then optional body+- Output only the commit message, no quotes or code blocks+</format>++<style>+- Imperative mood: "Add feature" not "Added feature"+- Match the style of commits being squashed (conventional commits if used)+- Describe the change, not the intent or benefit+</style>++<commits branch="{{ branch }}" target="{{ target_branch }}">+{% for commit in commits %}- {{ commit }}+{% endfor %}</commits>++<diffstat>+{{ git_diff_stat }}+</diffstat>++<diff>+{{ git_diff }}+</diff>++"""+```+<!-- DEFAULT_SQUASH_TEMPLATE_END -->+<!-- USER_CONFIG_END -->## Project config@@ -1731,12 +1838,10 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) || `CLICOLOR_FORCE` | Force colored output even when not a TTY |-<!-- subdoc: create -->-<!-- subdoc: show --><!-- subdoc: state -->-"#+"#))]Config {#[command(subcommand)]diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rsindex 68388c925..a0888cae6 100644--- a/tests/integration_tests/readme_sync.rs+++ b/tests/integration_tests/readme_sync.rs@@ -68,16 +68,22 @@ static TMPDIR_MAIN_REGEX: LazyLock<Regex> =/// Regex for REPO placeholderstatic REPO_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[REPO\]").unwrap());-/// Regex to find DEFAULT_TEMPLATE marker+/// Regex to extract user config section from src/cli/mod.rs+/// Matches content between USER_CONFIG_START and USER_CONFIG_END markers+static USER_CONFIG_PATTERN: LazyLock<Regex> = LazyLock::new(|| {+ Regex::new(r"(?s)<!-- USER_CONFIG_START -->\n(.*?)\n<!-- USER_CONFIG_END -->").unwrap()+});++/// Regex to find DEFAULT_TEMPLATE marker in user config section (markdown format)static DEFAULT_TEMPLATE_PATTERN: LazyLock<Regex> = LazyLock::new(|| {- Regex::new(r"(?s)(# <!-- DEFAULT_TEMPLATE_START -->\n).*?(# <!-- DEFAULT_TEMPLATE_END -->)")+ Regex::new(r"(?s)(<!-- DEFAULT_TEMPLATE_START -->\n).*?(<!-- DEFAULT_TEMPLATE_END -->)").unwrap()});-/// Regex to find DEFAULT_SQUASH_TEMPLATE marker+/// Regex to find DEFAULT_SQUASH_TEMPLATE marker in user config section (markdown format)static SQUASH_TEMPLATE_PATTERN: LazyLock<Regex> = LazyLock::new(|| {Regex::new(- r"(?s)(# <!-- DEFAULT_SQUASH_TEMPLATE_START -->\n).*?(# <!-- DEFAULT_SQUASH_TEMPLATE_END -->)",+ r"(?s)(<!-- DEFAULT_SQUASH_TEMPLATE_START -->\n).*?(<!-- DEFAULT_SQUASH_TEMPLATE_END -->)",).unwrap()});@@ -642,21 +648,6 @@ fn increase_heading_levels(content: &str) -> String {result.join("\n")}-/// Convert a template to commented TOML format-fn comment_template(template: &str) -> String {- template- .lines()- .map(|line| {- if line.is_empty() {- String::from("#")- } else {- format!("# {line}")- }- })- .collect::<Vec<_>>()- .join("\n")-}-/// Extract templates from llm.rs sourcefn extract_templates(content: &str) -> std::collections::HashMap<String, String> {RUST_RAW_STRING_PATTERN@@ -879,14 +870,101 @@ fn sync_readme_markers(}}+/// Transform user config markdown to config.example.toml format+///+/// # Design+///+/// The source content is the user config section in `src/cli/mod.rs`, embedded between+/// `<!-- USER_CONFIG_START -->` and `<!-- USER_CONFIG_END -->` markers. This markdown+/// is designed as a great explainer for configuration options, containing prose+/// explanations and TOML code blocks showing example values.+///+/// The generated file (`dev/config.example.toml`) is the entire source with every line+/// `# ` prefixed and code fence markers stripped. This creates a fully-commented config+/// file that serves as inline documentation — users read through, find what they want,+/// and uncomment the relevant `key = value` line.+///+/// # Transform Rules+///+/// 1. Code fence markers (```` ``` ````, ```` ```toml ````) → stripped entirely+/// 2. All other lines → prefixed with `# `+/// 3. Trailing empty comment lines → trimmed+fn transform_config_source_to_toml(source: &str) -> String {+ let mut result = Vec::new();+ let mut in_code_block = false;++ for line in source.lines() {+ let trimmed = line.trim();++ // Strip code fence markers+ if trimmed.starts_with("```") {+ in_code_block = !in_code_block;+ continue;+ }++ // Comment all lines+ if line.is_empty() {+ result.push(String::from("#"));+ } else {+ result.push(format!("# {}", line));+ }+ }++ // Clean up: remove trailing empty comment lines+ while result.last().is_some_and(|l| l == "#" || l.is_empty()) {+ result.pop();+ }++ result.join("\n")+}++/// Extract user config documentation from src/cli/mod.rs+///+/// The user config section is embedded in mod.rs between USER_CONFIG_START+/// and USER_CONFIG_END markers. This function extracts that content for+/// transforming into config.example.toml.+fn extract_user_config_from_cli(cli_mod_content: &str) -> String {+ USER_CONFIG_PATTERN+ .captures(cli_mod_content)+ .and_then(|cap| cap.get(1))+ .map(|m| m.as_str().to_string())+ .expect("USER_CONFIG_START/END markers not found in src/cli/mod.rs")+}+#[test]-fn test_config_example_templates_are_in_sync() {+fn test_config_source_generates_example_toml() {let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));- let llm_rs_path = project_root.join("src/llm.rs");+ let cli_mod_path = project_root.join("src/cli/mod.rs");let config_path = project_root.join("dev/config.example.toml");+ let cli_mod_content = fs::read_to_string(&cli_mod_path)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", cli_mod_path.display(), e));++ let user_config_content = extract_user_config_from_cli(&cli_mod_content);+ let expected = transform_config_source_to_toml(&user_config_content);+ let expected = trim_lines(&expected);++ let current = fs::read_to_string(&config_path)+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", config_path.display(), e));+ let current = trim_lines(¤t);++ if current != expected {+ fs::write(&config_path, format!("{}\n", expected)).unwrap();+ panic!(+ "config.example.toml out of sync with user config section in src/cli/mod.rs. \+ Run tests locally and commit the changes."+ );+ }+}++#[test]+fn test_config_source_templates_are_in_sync() {+ let project_root = Path::new(env!("CARGO_MANIFEST_DIR"));+ let llm_rs_path = project_root.join("src/llm.rs");+ let cli_mod_path = project_root.join("src/cli/mod.rs");+let llm_content = fs::read_to_string(&llm_rs_path).unwrap();- let config_content = fs::read_to_string(&config_path).unwrap();+ let cli_mod_content = fs::read_to_string(&cli_mod_path).unwrap();// Extract templates from llm.rslet templates = extract_templates(&llm_content);@@ -899,10 +977,10 @@ fn test_config_example_templates_are_in_sync() {"DEFAULT_SQUASH_TEMPLATE not found in src/llm.rs");- let mut updated_content = config_content.clone();+ let mut updated_content = cli_mod_content.clone();let mut updated_count = 0;- // Helper to replace a template section+ // Helper to replace a template section in markdown formatlet mut replace_template = |pattern: &Regex, name: &str, key: &str| {if let Some(cap) = pattern.captures(&updated_content.clone()) {let full_match = cap.get(0).unwrap();@@ -912,12 +990,15 @@ fn test_config_example_templates_are_in_sync() {let template = templates.get(name).unwrap_or_else(|| panic!("{name} not found in src/llm.rs"));- let commented = comment_template(template);+ // Format as markdown code blocklet replacement = format!(- r#"{prefix}# {key} = """-{commented}-# """+ r#"{prefix}```toml+[commit-generation]+{key} = """+{template}+"""+```{suffix}"#);@@ -936,9 +1017,9 @@ fn test_config_example_templates_are_in_sync() {);if updated_count > 0 {- fs::write(&config_path, &updated_content).unwrap();+ fs::write(&cli_mod_path, &updated_content).unwrap();panic!(- "Templates out of sync: updated {} section(s) in config.example.toml. \+ "Templates out of sync: updated {} section(s) in src/cli/mod.rs. \Run tests locally and commit the changes.",updated_count);diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex 5df514a28..d99467e59 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap@@ -46,101 +46,124 @@ Usage: [1m[36mwt config create[0m [36m[OPTIONS]Creates [2m~/.config/worktrunk/config.toml[0m with the following content:- [2m# Worktrunk Global Configuration- [2m# Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)+ [2m# # Worktrunk User Configuration+ [2m#+ [2m# Create with `wt config create`.+ [2m#+ [2m# Location:+ [2m#+ [2m# - macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)+ [2m# - Windows: `%APPDATA%\worktrunk\config.toml`+ [2m#+ [2m# ## Worktree Path Template+ [2m#+ [2m# Controls where new worktrees are created. Paths are relative to the repository root.+ [2m#+ [2m# **Variables:**+ [2m#+ [2m# - `{{ repo }}` — repository directory name+ [2m# - `{{ branch }}` — raw branch name (e.g., `feature/auth`)+ [2m# - `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)+ [2m# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)+ [2m#+ [2m# **Examples** for repo at `~/code/myproject`, branch `feature/auth`:+ [2m#+ [2m# # Default — siblings in parent directory+ [2m# # Creates: ~/code/myproject.feature-auth+ [2m# worktree-path = "../{{ repo }}.{{ branch | sanitize }}"+ [2m#+ [2m# # Inside the repository+ [2m# # Creates: ~/code/myproject/.worktrees/feature-auth+ [2m# worktree-path = ".worktrees/{{ branch | sanitize }}"+ [2m#+ [2m# # Namespaced (useful when multiple repos share a parent directory)+ [2m# # Creates: ~/code/worktrees/myproject/feature-auth+ [2m# worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"+ [2m#+ [2m# # Nested bare repo (git clone --bare <url> project/.git)+ [2m# # Creates: ~/code/project/feature-auth (sibling to .git)+ [2m# worktree-path = "../{{ branch | sanitize }}"+ [2m#+ [2m# ## List Command Defaults+ [2m#+ [2m# Persistent flag values for `wt list`. Override on command line as needed.+ [2m#+ [2m# [list]+ [2m# full = false # Show CI status and main…± diffstat columns (--full)+ [2m# branches = false # Include branches without worktrees (--branches)+ [2m# remotes = false # Include remote-only branches (--remotes)+ [2m#+ [2m# ## Commit Defaults+ [2m#+ [2m# Shared by `wt step commit`, `wt step squash`, and `wt merge`.+ [2m#+ [2m# [commit]+ [2m# stage = "all" # What to stage before commit: "all", "tracked", or "none"+ [2m#+ [2m# ## Merge Command Defaults+ [2m#+ [2m# All flags are on by default. Set to false to change default behavior.+ [2m#+ [2m# [merge]+ [2m# squash = true # Squash commits into one (--no-squash to preserve history)+ [2m# commit = true # Commit uncommitted changes first (--no-commit to skip)+ [2m# rebase = true # Rebase onto target before merge (--no-rebase to skip)+ [2m# remove = true # Remove worktree after merge (--no-remove to keep)+ [2m# verify = true # Run project hooks (--no-verify to skip)+ [2m#+ [2m# ## Select Command Defaults+ [2m#+ [2m# Pager behavior for `wt select` diff previews.+ [2m#+ [2m# [select]+ [2m# # Pager command with flags for diff preview (overrides git's core.pager)+ [2m# # Use this to specify pager flags needed for non-TTY contexts+ [2m# # Example:+ [2m# # pager = "delta --paging=never"+ [2m#+ [2m# ## LLM Commit Messages+ [2m#+ [2m# Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.+ [2m#+ [2m# Using [llm](https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):[2m#- [2m# Alternative locations (XDG Base Directory spec):- [2m# macOS/Linux: $XDG_CONFIG_HOME/worktrunk/config.toml- [2m# Windows: %APPDATA%\worktrunk\config.toml- [2m- [2m# Commit Message Generation (Optional)- [2m# For generating commit messages during merge operations (wt merge)[2m# [commit-generation]- [2m# Example: Simon Willison's llm CLI (https://github.com/simonw/llm)- [2m# Install: pip install llm llm-anthropic[2m# command = "llm"[2m# args = ["-m", "claude-haiku-4.5"]- [2m- [2m# Alternative: AIChat - Rust-based, supports 20+ providers- [2m# Install from: https://github.com/sigoden/aichat+ [2m#+ [2m# Using [aichat](https://github.com/sigoden/aichat):+ [2m#+ [2m# [commit-generation][2m# command = "aichat"[2m# args = ["-m", "claude:claude-haiku-4.5"]- [2m- [2m# Optional: Load template from file (mutually exclusive with 'template')- [2m# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt- [2m# template-file = "~/.config/worktrunk/commit-template.txt"- [2m- [2m# Optional: Load squash template from file (mutually exclusive with 'squash-template')- [2m# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt- [2m# squash-template-file = "~/.config/worktrunk/squash-template.txt"- [2m- [2m# See "Custom Prompt Templates" section at end of file for inline template options.- [2m- [2m# Worktree Path Template- [2m# Variables:- [2m# {{ repo }} - Repository directory name (e.g., "myproject")- [2m# {{ branch }} - Raw branch name (e.g., "feature/auth")- [2m# {{ branch | sanitize }} - Filesystem-safe: / and \ replaced by - (e.g., "feature-auth")- [2m# {{ branch | sanitize_db }} - Database-safe: lowercase, underscores, hash suffix (e.g., "feature_auth_x7k")- [2m#- [2m# Paths are relative to the main worktree root (original repository directory).- [2m#- [2m# Example paths created (repo at /Users/dev/myproject, branch feature/auth):- [2m# "../{{ repo }}.{{ branch | sanitize }}" → /Users/dev/myproject.feature-auth- [2m# ".worktrees/{{ branch | sanitize }}" → /Users/dev/myproject/.worktrees/feature-auth- [2mworktree-path = "../{{ repo }}.{{ branch | sanitize }}"- [2m- [2m# Alternative: Inside repo (useful for bare repos)- [2m# worktree-path = ".worktrees/{{ branch | sanitize }}"- [2m- [2m# List Command Defaults- [2m# Configure default behavior for `wt list`- [2m[list]- [2mfull = false # Show CI and default-branch merge-base diffstat (`main…±` column) by default- [2mbranches = false # Include branches without worktrees by default- [2mremotes = false # Include remote branches by default- [2mtimeout-ms = 0 # (Experimental) Per-task timeout in ms; 0 = no timeout; --full disables- [2m- [2m# Commit Defaults (shared by `wt step commit`, `wt step squash`, and `wt merge`)- [2m[commit]- [2mstage = "all" # What to stage: "all", "tracked", or "none"- [2m- [2m# Merge Command Defaults- [2m# Note: `stage` defaults from [commit] section above- [2m[merge]- [2msquash = true # Squash commits when merging- [2mcommit = true # Commit uncommitted changes during merge (disables squash when false)- [2mrebase = true # Rebase onto target before merging- [2mremove = true # Remove worktree after merge- [2mverify = true # Run project hooks- [2m- [2m# Select Command Defaults- [2m# Configure pager behavior for `wt select` diff previews- [2m[select]- [2m# Pager command with flags for diff preview (overrides git's core.pager)- [2m# Use this to specify pager flags needed for non-TTY contexts- [2m# Example: pager = "delta --paging=never"- [2m- [2m# Approved Commands- [2m# Commands approved for project hooks in this repo- [2m# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`- [2m[projects."github.com/user/repo"]- [2mapproved-commands = ["npm ci", "npm test"]- [2m- [2m# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),- [2m# use a separate PROJECT config file at <repo>/.config/wt.toml- [2m# Run `wt config create --project` to create one, or see https://worktrunk.dev/hook/- [2m- [2m# ============================================================================- [2m# Custom Prompt Templates (Advanced)- [2m# ============================================================================- [2m# These options belong under [commit-generation] section above.- [2m# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`- [2m- [2m# Optional: Custom prompt template (inline) - Uses minijinja syntax- [2m# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}- [2m# If not specified, uses the default template shown below:+ [2m#+ [2m# See [Custom Prompt Templates](#custom-prompt-templates) for inline template options.+ [2m#+ [2m# ## Approved Commands+ [2m#+ [2m# Commands approved for project hooks. Auto-populated when approving hooks on first run, or via `wt hook approvals add`.+ [2m#+ [2m# [projects."github.com/user/repo"]+ [2m# approved-commands = ["npm ci", "npm test"]+ [2m#+ [2m# For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see <https://worktrunk.dev/hook/>.+ [2m#+ [2m# ## Custom Prompt Templates+ [2m#+ [2m# Templates use [minijinja](https://docs.rs/minijinja/) syntax.+ [2m#+ [2m# ### Commit Template+ [2m#+ [2m# Available variables:+ [2m#+ [2m# - `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content+ [2m# - `{{ branch }}`, `{{ repo }}` — context+ [2m# - `{{ recent_commits }}` — recent commit messages+ [2m#+ [2m# Default template:+ [2m#[2m# <!-- DEFAULT_TEMPLATE_START -->+ [2m# [commit-generation][2m# template = """[2m# Write a commit message for the staged changes below.[2m#@@ -169,37 +192,21 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[2m# {% for commit in recent_commits %}- {{ commit }}[2m# {% endfor %}</recent_commits>{% endif %}[2m# </context>+ [2m#[2m# """[2m# <!-- DEFAULT_TEMPLATE_END -->[2m#- [2m# Example alternative template with different style:- [2m# template = """- [2m# Generate a commit message for {{ repo | upper }}.+ [2m# ### Squash Template[2m#- [2m# Branch: {{ branch }}- [2m# {%- if recent_commits %}+ [2m# Available variables (in addition to commit template variables):[2m#- [2m# Recent commit style ({{ recent_commits | length }} commits):- [2m# {%- for commit in recent_commits %}- [2m# {{ loop.index }}. {{ commit }}- [2m# {%- endfor %}- [2m# {%- endif %}+ [2m# - `{{ commits }}` — list of commits being squashed+ [2m# - `{{ target_branch }}` — merge target branch[2m#- [2m# Changes to commit:- [2m# ```- [2m# {{ git_diff }}- [2m# ```+ [2m# Default template:[2m#- [2m# Requirements:- [2m# - Follow the style of recent commits above- [2m# - First line under 50 chars- [2m# - Focus on WHY, not HOW- [2m# """- [2m- [2m# Optional: Custom squash commit message template (inline) - Uses minijinja syntax- [2m# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}, {{ commits }}, {{ target_branch }}- [2m# If not specified, uses the default template:[2m# <!-- DEFAULT_SQUASH_TEMPLATE_START -->+ [2m# [commit-generation][2m# squash-template = """[2m# Combine these commits into a single commit message.[2m#@@ -225,25 +232,9 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[2m# <diff>[2m# {{ git_diff }}[2m# </diff>- [2m# """- [2m# <!-- DEFAULT_SQUASH_TEMPLATE_END -->[2m#- [2m# Example alternative template:- [2m# squash-template = """- [2m# Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.- [2m#- [2m# {% if commits | length > 1 -%}- [2m# Commits being combined:- [2m# {%- for c in commits %}- [2m# {{ loop.index }}/{{ loop.length }}: {{ c }}- [2m# {%- endfor %}- [2m# {%- else -%}- [2m# Single commit: {{ commits[0] }}- [2m# {%- endif %}- [2m#- [2m# Generate one cohesive commit message that captures the overall change.- [2m# Use conventional commit format (feat/fix/docs/refactor).[2m# """+ [2m# <!-- DEFAULT_SQUASH_TEMPLATE_END -->[32mProject configdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 31050c640..d8f522cc0 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -46,13 +46,6 @@ Usage: [1m[36mwt config[0m [36m[OPTIONS][0m [36m<COMMAND>Manages configuration, shell integration, and runtime settings.-Worktrunk uses two configuration files:-- File Location Purpose- ────────────── ─────────────────────────────── ──────────────────────────────────────────────────────────────- User config ~/.config/worktrunk/config.toml Personal settings, command defaults, approved project commands- Project config .config/wt.toml Lifecycle hooks, checked into version control-[32mExamplesInstall shell integration (required for directory switching):@@ -71,96 +64,198 @@ Show current configuration and file locations:[2mwt config show-[32mUser config+[32mConfiguration files++ File Location Purpose+ ────────────── ─────────────────────────────── ──────────────────────────────────────────────────────────────+ User config ~/.config/worktrunk/config.toml Personal settings, command defaults, approved project commands+ Project config .config/wt.toml Lifecycle hooks, checked into version control++[32mWorktrunk User Configuration-The user config stores personal preferences that apply across all repositories. Create it with [2mwt config create[0m and view with [2mwt config show[0m.+Create with [2mwt config create[0m.-[1mWorktree path template+Location:-Controls where new worktrees are created. The template is relative to the repository root.+- macOS/Linux: [2m~/.config/worktrunk/config.toml[0m (or [2m$XDG_CONFIG_HOME[0m if set)+- Windows: [2m%APPDATA%\worktrunk\config.toml++[32mWorktree Path Template++Controls where new worktrees are created. Paths are relative to the repository root.++[1mVariables:-[1mAvailable variables:- [2m{{ repo }}[0m — repository directory name- [2m{{ branch }}[0m — raw branch name (e.g., [2mfeature/auth[0m)-- [2m{{ branch | sanitize }}[0m — branch name with [2m/[0m and [2m\[0m replaced by [2m-+- [2m{{ branch | sanitize }}[0m — filesystem-safe: [2m/[0m and [2m\[0m become [2m-[0m (e.g., [2mfeature-auth[0m)+- [2m{{ branch | sanitize_db }}[0m — database-safe: lowercase, underscores, hash suffix (e.g., [2mfeature_auth_x7k[0m)-[1mExamples[0m for a repo at [2m~/code/myproject[0m creating branch [2mfeature/login[0m:+[1mExamples[0m for repo at [2m~/code/myproject[0m, branch [2mfeature/auth[0m:[2m# Default — siblings in parent directory- [2m# Creates: ~/code/myproject.feature-login+ [2m# Creates: ~/code/myproject.feature-auth[2mworktree-path = "../{{ repo }}.{{ branch | sanitize }}"[2m[2m# Inside the repository- [2m# Creates: ~/code/myproject/.worktrees/feature-login+ [2m# Creates: ~/code/myproject/.worktrees/feature-auth[2mworktree-path = ".worktrees/{{ branch | sanitize }}"[2m[2m# Namespaced (useful when multiple repos share a parent directory)- [2m# Creates: ~/code/worktrees/myproject/feature-login+ [2m# Creates: ~/code/worktrees/myproject/feature-auth[2mworktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"[2m[2m# Nested bare repo (git clone --bare <url> project/.git)- [2m# Creates: ~/code/project/feature-login (sibling to .git)+ [2m# Creates: ~/code/project/feature-auth (sibling to .git)[2mworktree-path = "../{{ branch | sanitize }}"-[1mCommand settings+[32mList Command Defaults-Set persistent flag values for commands. These apply unless explicitly overridden on the command line.--[1m[2mwt list[0m:+Persistent flag values for [2mwt list[0m. Override on command line as needed.[2m[list]- [2m# All off by default- [2mfull = true # --full- [2mbranches = true # --branches- [2mremotes = true # --remotes+ [2mfull = false # Show CI status and main…± diffstat columns (--full)+ [2mbranches = false # Include branches without worktrees (--branches)+ [2mremotes = false # Include remote-only branches (--remotes)++[32mCommit Defaults-[1m[2mwt step commit[0m and [2mwt merge[0m staging:+Shared by [2mwt step commit[0m, [2mwt step squash[0m, and [2mwt merge[0m.[2m[commit]- [2mstage = "all" # "all" (default), "tracked", or "none"+ [2mstage = "all" # What to stage before commit: "all", "tracked", or "none"++[32mMerge Command Defaults-[1m[2mwt merge[0m:+All flags are on by default. Set to false to change default behavior.[2m[merge]- [2m# These flags are on by default; set to false to disable- [2msquash = false # Preserve individual commits (--no-squash)- [2mcommit = false # Skip committing uncommitted changes (also disables squash)- [2mrebase = false # Skip rebase (fails if not already rebased)- [2mremove = false # Keep worktree after merge (--no-remove)- [2mverify = false # Skip hooks (--no-verify)+ [2msquash = true # Squash commits into one (--no-squash to preserve history)+ [2mcommit = true # Commit uncommitted changes first (--no-commit to skip)+ [2mrebase = true # Rebase onto target before merge (--no-rebase to skip)+ [2mremove = true # Remove worktree after merge (--no-remove to keep)+ [2mverify = true # Run project hooks (--no-verify to skip)-[1mLLM commit messages+[32mSelect Command Defaults-Configure automatic commit message generation. Requires an external tool like llm:+Pager behavior for [2mwt select[0m diff previews.++ [2m[select]+ [2m# Pager command with flags for diff preview (overrides git's core.pager)+ [2m# Use this to specify pager flags needed for non-TTY contexts+ [2m# Example:+ [2m# pager = "delta --paging=never"++[32mLLM Commit Messages++Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.++Using llm (install: [2mpip install llm llm-anthropic[0m):[2m[commit-generation][2mcommand = "llm"[2margs = ["-m", "claude-haiku-4.5"]-See LLM Commit Messages for setup details and template customization.+Using aichat:++ [2m[commit-generation]+ [2mcommand = "aichat"+ [2margs = ["-m", "claude:claude-haiku-4.5"]-[1mApproved commands+See Custom Prompt Templates for inline template options.-When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:+[32mApproved Commands- [2m[projects."my-project"]+Commands approved for project hooks. Auto-populated when approving hooks on first run, or via [2mwt hook approvals add[0m.++ [2m[projects."github.com/user/repo"][2mapproved-commands = ["npm ci", "npm test"]-Manage approvals with [2mwt hook approvals add[0m to review and pre-approve commands, and [2mwt hook approvals clear[0m to reset (add [2m--global[0m to clear all projects).+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at [2m<repo>/.config/wt.toml[0m. Run [2mwt config create --project[0m to create one, or see <https://worktrunk.dev/hook/>.-[1mUser hooks+[32mCustom Prompt Templates-Personal hooks that run for all repositories. Use the same syntax as project hooks:+Templates use minijinja syntax.- [2m[post-create]- [2msetup = "echo 'Setting up worktree...'"+[1mCommit Template++Available variables:++- [2m{{ git_diff }}[0m, [2m{{ git_diff_stat }}[0m — diff content+- [2m{{ branch }}[0m, [2m{{ repo }}[0m — context+- [2m{{ recent_commits }}[0m — recent commit messages++Default template:++ [2m[commit-generation]+ [2mtemplate = """+ [2mWrite a commit message for the staged changes below.[2m- [2m[pre-merge]- [2mnotify = "notify-send 'Merging {{ branch }}'"+ [2m<format>+ [2m- Subject under 50 chars, blank line, then optional body+ [2m- Output only the commit message, no quotes or code blocks+ [2m</format>+ [2m+ [2m<style>+ [2m- Imperative mood: "Add feature" not "Added feature"+ [2m- Match recent commit style (conventional commits if used)+ [2m- Describe the change, not the intent or benefit+ [2m</style>+ [2m+ [2m<diffstat>+ [2m{{ git_diff_stat }}+ [2m</diffstat>+ [2m+ [2m<diff>+ [2m{{ git_diff }}+ [2m</diff>+ [2m+ [2m<context>+ [2mBranch: {{ branch }}+ [2m{% if recent_commits %}<recent_commits>+ [2m{% for commit in recent_commits %}- {{ commit }}+ [2m{% endfor %}</recent_commits>{% endif %}+ [2m</context>+ [2m+ [2m"""++[1mSquash Template++Available variables (in addition to commit template variables):-User hooks run before project hooks and don't require approval. Skip with [2m--no-verify[0m.+- [2m{{ commits }}[0m — list of commits being squashed+- [2m{{ target_branch }}[0m — merge target branch-See [2mwt hook[0m for complete documentation.+Default template:++ [2m[commit-generation]+ [2msquash-template = """+ [2mCombine these commits into a single commit message.+ [2m+ [2m<format>+ [2m- Subject under 50 chars, blank line, then optional body+ [2m- Output only the commit message, no quotes or code blocks+ [2m</format>+ [2m+ [2m<style>+ [2m- Imperative mood: "Add feature" not "Added feature"+ [2m- Match the style of commits being squashed (conventional commits if used)+ [2m- Describe the change, not the intent or benefit+ [2m</style>+ [2m+ [2m<commits branch="{{ branch }}" target="{{ target_branch }}">+ [2m{% for commit in commits %}- {{ commit }}+ [2m{% endfor %}</commits>+ [2m+ [2m<diffstat>+ [2m{{ git_diff_stat }}+ [2m</diffstat>+ [2m+ [2m<diff>+ [2m{{ git_diff }}+ [2m</diff>+ [2m+ [2m"""[32mProject config