Skip to content

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

feat: Add custom prompt templates and update documentation

Maximilian Roosb2901047a49a
diff --git a/README.md b/README.md
index a714a0d97..c7ed878ab 100644
--- a/README.md
+++ b/README.md
@@ -102,88 +102,9 @@ Set up LLM integration: run `wt config help` to see the setup guide, or `wt conf
<details>
<summary><b>Advanced: Custom Prompt Templates</b></summary>
-Worktrunk uses [minijinja templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for commit message prompts, giving you full control over what the LLM sees.
+Worktrunk uses [minijinja templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for commit message prompts. Customize the prompts by setting `template` (inline) or `template-file` (external file) in the `[commit-generation]` section. Use `squash-template` / `squash-template-file` for squash commits.
-**Inline template for normal commits:**
-
-```toml
-[commit-generation]
-command = "llm"
-args = ["-s"]
-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
-"""
-```
-
-**Inline template for squash commits:**
-
-```toml
-[commit-generation]
-command = "llm"
-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).
-"""
-```
-
-**External template files:**
-
-```toml
-[commit-generation]
-command = "claude"
-template-file = "~/.config/worktrunk/commit-template.jinja"
-squash-template-file = "~/.config/worktrunk/squash-template.jinja"
-```
-
-**Available template variables:**
-
-Normal commits:
-
-- `{{ git_diff }}` - Staged changes
-- `{{ branch }}` - Current branch name
-- `{{ recent_commits }}` - Array of recent commit messages (for style matching)
-- `{{ repo }}` - Repository name
-
-Squash commits:
-
-- `{{ commits }}` - Array of commit messages being squashed
-- `{{ target_branch }}` - Branch being merged into (e.g., "main")
-- `{{ branch }}` - Current branch name
-- `{{ repo }}` - Repository name
-
-See the [minijinja template documentation](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for complete syntax reference (filters, conditionals, loops, whitespace control, etc.).
+See [`config.example.toml`](config.example.toml) for complete template examples with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`, `target_branch`, `repo`).
</details>
diff --git a/config.example.toml b/config.example.toml
index 41b36956a..6c5deea68 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -4,6 +4,12 @@
# Windows: %APPDATA%\worktrunk\config.toml
#
# Generate with: wt config init
+#
+# NOTE: This file is the source of truth for default configuration.
+# The commented templates below match src/llm.rs constants:
+# - DEFAULT_TEMPLATE (lines 41-76)
+# - DEFAULT_SQUASH_TEMPLATE (lines 109-118)
+# When changing these constants, update the commented sections here to match.
# Worktree Path Template
# Variables: {{ main_worktree }} = main worktree directory name, {{ branch }} = branch name
@@ -30,7 +36,7 @@ worktree-path = "../{{ main_worktree }}.{{ branch }}"
# command = "aichat"
# args = ["-m", "claude:claude-haiku-4.5"]
-# Optional: Custom prompt template (inline) - Uses Jinja2 syntax
+# Optional: Custom prompt template (inline) - Uses minijinja syntax
# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
# If not specified, uses the default template shown below:
# template = """
@@ -69,12 +75,36 @@ worktree-path = "../{{ main_worktree }}.{{ branch }}"
# {% endif %}
# </git-info>
# """
+#
+# 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: Load template from file (mutually exclusive with 'template')
# Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
# template-file = "~/.config/worktrunk/commit-template.txt"
-# Optional: Custom squash commit message template (inline) - Uses Jinja2 syntax
+# Optional: Custom squash commit message template (inline) - Uses minijinja syntax
# Available variables: {{ commits }}, {{ target_branch }}, {{ branch }}, {{ repo }}
# If not specified, uses the default template:
# squash-template = """
@@ -87,6 +117,23 @@ worktree-path = "../{{ main_worktree }}.{{ branch }}"
# - {{ commit }}
# {% endfor %}
# """
+#
+# 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).
+# """
# Optional: Load squash template from file (mutually exclusive with 'squash-template')
# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 140136cd9..c3af8d33e 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -81,7 +81,8 @@ fn display_global_config() -> Result<(), GitError> {
println!("{HINT_EMOJI} {HINT}Not found (using defaults){HINT:#}");
println!("{HINT_EMOJI} {HINT}Run 'wt config init' to create a config file{HINT:#}");
println!();
- let default_config = "# Default configuration:\nworktree-path = \"../{{repo}}.{{branch}}\"";
+ let default_config =
+ "# Default configuration:\nworktree-path = \"../{{ main_worktree }}.{{ branch }}\"";
print!("{}", format_toml(default_config, ""));
return Ok(());
}
diff --git a/src/llm.rs b/src/llm.rs
index 8d7e6c209..b25f7d349 100644
--- a/src/llm.rs
+++ b/src/llm.rs
@@ -13,6 +13,9 @@ struct PromptContext<'a> {
}
/// Default template for commit message prompts
+///
+/// TODO: Generate config.example.toml dynamically to keep templates in sync.
+/// Currently this constant must be manually copied to config.example.toml (lines 41-76).
const DEFAULT_TEMPLATE: &str = r#"Format
- First line: <50 chars, present tense, describes WHAT and WHY (not HOW).
- Blank line after first line.
@@ -50,6 +53,9 @@ The following is the context for your task:
"#;
/// Default template for squash commit message prompts
+///
+/// TODO: Generate config.example.toml dynamically to keep templates in sync.
+/// Currently this constant must be manually copied to config.example.toml (lines 109-118).
const DEFAULT_SQUASH_TEMPLATE: &str = r#"Generate a conventional commit message (feat/fix/docs/style/refactor) that combines these changes into one cohesive message. Output only the commit message without any explanation.
Squashing commits on current branch since branching from {{ target_branch }}