Skip to content

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.md
index 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 |
-
## Examples
Install 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-auth
worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
-# Creates: ~/code/myproject/.worktrees/feature-login
+# 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-login
+# 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-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 &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
- Working directory for this command
-
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 show
Shows location and contents of user config (`~/.config/worktrunk/config.toml`)
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 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.md
index 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 |
-
## Examples
Install 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-auth
worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
-# Creates: ~/code/myproject/.worktrees/feature-login
+# 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-login
+# 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-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> <spa
Show 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 &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
- Working directory for this command
-
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</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 show
Shows location and contents of user config (`~/.config/worktrunk/config.toml`)
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 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-auth
worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
-# Creates: ~/code/myproject/.worktrees/feature-login
+# 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-login
+# 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-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.rs
index 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 placeholder
static 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 source
fn 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(&current);
+
+ 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.rs
let 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 format
let 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 block
let 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.snap
index 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: wt config create [OPTIONS]
Creates ~/.config/worktrunk/config.toml with the following content:
- # Worktrunk Global Configuration
- # Copy to: ~/.config/worktrunk/config.toml (or use `wt config create`)
+ # # 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`):
#
- # 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
+ #
+ # 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.
#
@@ -169,37 +192,21 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# {% 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.
#
@@ -225,25 +232,9 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# <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 -->
Project config
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 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: wt config [OPTIONS] <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
-
Examples
Install shell integration (required for directory switching):
@@ -71,96 +64,198 @@ 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
+
+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:
# Default — siblings in parent directory
- # Creates: ~/code/myproject.feature-login
+ # Creates: ~/code/myproject.feature-auth
worktree-path = "../{{ repo }}.{{ branch | sanitize }}"

# Inside the repository
- # Creates: ~/code/myproject/.worktrees/feature-login
+ # 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-login
+ # 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-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.
[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)
+
+Commit Defaults
-wt step commit and wt merge staging:
+Shared by wt step commit, wt step squash, and wt merge.
[commit]
- stage = "all" # "all" (default), "tracked", or "none"
+ stage = "all" # What to stage before commit: "all", "tracked", or "none"
+
+Merge Command Defaults
-wt merge:
+All flags are on by default. Set to false to change default behavior.
[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:
+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 (install: pip install llm llm-anthropic):
[commit-generation]
command = "llm"
args = ["-m", "claude-haiku-4.5"]
-See LLM Commit Messages for setup details and template customization.
+Using aichat:
+
+ [commit-generation]
+ command = "aichat"
+ args = ["-m", "claude:claude-haiku-4.5"]
-Approved 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:
+Approved Commands
- [projects."my-project"]
+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"]
-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/>.
-User hooks
+Custom Prompt Templates
-Personal hooks that run for all repositories. Use the same syntax as project hooks:
+Templates use minijinja syntax.
- [post-create]
- setup = "echo 'Setting up worktree...'"
+Commit Template
+
+Available variables:
+
+- {{ git_diff }}, {{ git_diff_stat }} — diff content
+- {{ branch }}, {{ repo }} — context
+- {{ recent_commits }} — recent commit messages
+
+Default template:
+
+ [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>
+ 
+ """
+
+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 for complete documentation.
+Default template:
+
+ [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>
+ 
+ """
Project config