Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: Improve config and template clarity

Maximilian Roos77618d7339fb
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index 675b46f37..758764a0a 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -140,16 +140,7 @@ $ wt merge
For more details: `wt config --help`
-<details>
-<summary>Advanced: Custom Prompt Templates</summary>
-
-Customize commit message prompts using [minijinja
-templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html).
-
-See [`config.example.toml`](dev/config.example.toml) for template examples with all
-available variables.
-
-</details>
+**Custom prompt templates:** Run `wt config create` to generate an example config with minijinja template variables.
### Project Hooks
@@ -784,54 +775,9 @@ See `wt step --help` for details.
```bash
wt config list # Show all config files and locations
wt config create # Create global config with examples
-wt config --help # Show LLM setup guide
+wt config --help # Show setup guide, file locations, and options
```
-<details>
-<summary>Configuration details</summary>
-
-**Global config** (loaded in order of precedence):
-
-1. `WORKTRUNK_CONFIG_PATH` environment variable
-2. `~/.config/worktrunk/config.toml` (Linux/macOS) or `%APPDATA%\worktrunk\config.toml` (Windows)
-
-Contents:
-
-- `worktree-path` - Path template for new worktrees
-- `[list]` - Default display options for `wt list` (full, branches, remotes)
-- `[commit-generation]` - LLM command and prompt templates
-- `[projects."project-id"]` - Per-project approved commands (auto-populated)
-
-**Project config** (`.config/wt.toml` in repository root):
-
-- `[post-create-command]` - Commands after worktree creation
-- `[post-start-command]` - Background commands after creation
-- `[pre-commit-command]` - Validation before committing
-- `[pre-merge-command]` - Validation before merge
-- `[post-merge-command]` - Cleanup after merge
-
----
-
-**Example global config** (`~/.config/worktrunk/config.toml`):
-
-```toml
-worktree-path = "../{{ main_worktree }}.{{ branch }}"
-
-[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
-
-# Approved commands (auto-populated when approving project hooks)
-[projects."github.com/user/repo"]
-approved-commands = ["npm install", "npm test"]
-```
-
-**Example project config** (`.config/wt.toml`): See Project Hooks section above.
-
-**Path template defaults:** `../{{ main_worktree }}.{{ branch }}` (siblings to main repo). Available variables: `{{ main_worktree }}`, `{{ branch }}`, `{{ repo }}`.
-
-</details>
-
## Advanced Features
### Custom Worktree Status
diff --git a/README.md b/README.md
index 675b46f37..758764a0a 100644
--- a/README.md
+++ b/README.md
@@ -140,16 +140,7 @@ $ wt merge
For more details: `wt config --help`
-<details>
-<summary>Advanced: Custom Prompt Templates</summary>
-
-Customize commit message prompts using [minijinja
-templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html).
-
-See [`config.example.toml`](dev/config.example.toml) for template examples with all
-available variables.
-
-</details>
+**Custom prompt templates:** Run `wt config create` to generate an example config with minijinja template variables.
### Project Hooks
@@ -784,54 +775,9 @@ See `wt step --help` for details.
```bash
wt config list # Show all config files and locations
wt config create # Create global config with examples
-wt config --help # Show LLM setup guide
+wt config --help # Show setup guide, file locations, and options
```
-<details>
-<summary>Configuration details</summary>
-
-**Global config** (loaded in order of precedence):
-
-1. `WORKTRUNK_CONFIG_PATH` environment variable
-2. `~/.config/worktrunk/config.toml` (Linux/macOS) or `%APPDATA%\worktrunk\config.toml` (Windows)
-
-Contents:
-
-- `worktree-path` - Path template for new worktrees
-- `[list]` - Default display options for `wt list` (full, branches, remotes)
-- `[commit-generation]` - LLM command and prompt templates
-- `[projects."project-id"]` - Per-project approved commands (auto-populated)
-
-**Project config** (`.config/wt.toml` in repository root):
-
-- `[post-create-command]` - Commands after worktree creation
-- `[post-start-command]` - Background commands after creation
-- `[pre-commit-command]` - Validation before committing
-- `[pre-merge-command]` - Validation before merge
-- `[post-merge-command]` - Cleanup after merge
-
----
-
-**Example global config** (`~/.config/worktrunk/config.toml`):
-
-```toml
-worktree-path = "../{{ main_worktree }}.{{ branch }}"
-
-[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
-
-# Approved commands (auto-populated when approving project hooks)
-[projects."github.com/user/repo"]
-approved-commands = ["npm install", "npm test"]
-```
-
-**Example project config** (`.config/wt.toml`): See Project Hooks section above.
-
-**Path template defaults:** `../{{ main_worktree }}.{{ branch }}` (siblings to main repo). Available variables: `{{ main_worktree }}`, `{{ branch }}`, `{{ repo }}`.
-
-</details>
-
## Advanced Features
### Custom Worktree Status
diff --git a/src/cli.rs b/src/cli.rs
index 1e1478134..c1aaf82e8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -471,6 +471,36 @@ For OpenAI:
Use 'wt config list' to view your current configuration
Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
+
+CONFIGURATION FILES:
+
+Global config (loaded in order of precedence):
+1. WORKTRUNK_CONFIG_PATH environment variable
+2. ~/.config/worktrunk/config.toml (Linux/macOS)
+ %APPDATA%\worktrunk\config.toml (Windows)
+
+Global config contents:
+- worktree-path: Path template for new worktrees
+- [list]: Default display options for 'wt list'
+- [commit-generation]: LLM command and prompt templates
+- [projects."project-id"]: Per-project approved commands (auto-populated)
+
+Project config (.config/wt.toml in repository root):
+- [post-create-command]: Commands after worktree creation
+- [post-start-command]: Background commands after creation
+- [pre-commit-command]: Validation before committing
+- [pre-merge-command]: Validation before merge
+- [post-merge-command]: Cleanup after merge
+
+Path template variables: {{ main_worktree }}, {{ branch }}, {{ repo }}
+Default: "../{{ main_worktree }}.{{ branch }}" (worktrees as siblings)
+
+CUSTOM PROMPT TEMPLATES:
+
+Customize commit message prompts using minijinja templates.
+Available variables: diff, files, commits, commit_count, branch, target.
+Run 'wt config create' to generate example config with template examples.
+Docs: https://docs.rs/minijinja/latest/minijinja/syntax/
"#
)]
Config {
diff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snap
index 9474741ea..c74dd7691 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -74,4 +75,34 @@ For OpenAI:
Use 'wt config list' to view your current configuration
Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
+CONFIGURATION FILES:
+
+Global config (loaded in order of precedence):
+1. WORKTRUNK_CONFIG_PATH environment variable
+2. ~/.config/worktrunk/config.toml (Linux/macOS)
+ %APPDATA%\worktrunk\config.toml (Windows)
+
+Global config contents:
+- worktree-path: Path template for new worktrees
+- [list]: Default display options for 'wt list'
+- [commit-generation]: LLM command and prompt templates
+- [projects."project-id"]: Per-project approved commands (auto-populated)
+
+Project config (.config/wt.toml in repository root):
+- [post-create-command]: Commands after worktree creation
+- [post-start-command]: Background commands after creation
+- [pre-commit-command]: Validation before committing
+- [pre-merge-command]: Validation before merge
+- [post-merge-command]: Cleanup after merge
+
+Path template variables: {{ main_worktree }}, {{ branch }}, {{ repo }}
+Default: "../{{ main_worktree }}.{{ branch }}" (worktrees as siblings)
+
+CUSTOM PROMPT TEMPLATES:
+
+Customize commit message prompts using minijinja templates.
+Available variables: diff, files, commits, commit_count, branch, target.
+Run 'wt config create' to generate example config with template examples.
+Docs: https://docs.rs/minijinja/latest/minijinja/syntax/
+
----- stderr -----