Skip to content

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

Docs: Create dedicated page for LLM commits

Maximilian Roos303b88d63698
diff --git a/docs/content/configuration.md b/docs/content/configuration.md
index 0b4374e59..3b63088cd 100644
--- a/docs/content/configuration.md
+++ b/docs/content/configuration.md
@@ -23,35 +23,35 @@ test = "npm test"
lint = "npm run lint"
```
-## LLM Commit Messages
+### Hook execution
-Worktrunk can invoke external commands to generate commit messages. [llm](https://llm.datasette.io/) from Simon Willison is recommended.
+<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_post_create.snap — edit source to update -->
-### Setup
+{% terminal() %}
+<span class="prompt">$</span> wt switch --create feature-x
+🔄 <span style='color:var(--cyan,#0aa)'>Running post-create <b>install</b>:</span>
+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> sync</span>
-1. Install llm:
- ```bash
- $ uv tool install -U llm
- ```
+ Resolved 24 packages in 145ms
+ Installed 24 packages in 1.2s
+✅ <span style='color:var(--green,#0a0)'>Created new worktree for <b>feature-x</b> from <b>main</b> at <b>../repo.feature-x</b></span>
+🔄 <span style='color:var(--cyan,#0aa)'>Running post-start <b>dev</b>:</span>
+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> run dev</span>
+{% end %}
-2. Configure your API key:
- ```bash
- $ llm install llm-anthropic
- $ llm keys set anthropic
- ```
+<!-- END AUTO-GENERATED -->
-3. Add to user config (`~/.config/worktrunk/config.toml`):
- ```toml
- [commit-generation]
- command = "llm"
- args = ["-m", "claude-haiku-4-5-20251001"]
- ```
+**Security**: Project commands require approval on first run. Approvals are saved to user config. Use `--force` to bypass prompts or `--no-verify` to skip hooks entirely.
-### Usage
+### Template variables
-`wt merge` generates commit messages automatically, or run `wt step commit` for just the commit step.
+Hooks can use these variables:
-For custom prompt templates, see `wt config --help`.
+- `{{ repo }}` — Repository name
+- `{{ branch }}` — Branch name
+- `{{ worktree }}` — Worktree path
+- `{{ repo_root }}` — Repository root path
+- `{{ target }}` — Target branch (for merge hooks)
## User Config Reference
@@ -70,10 +70,10 @@ This creates `~/.config/worktrunk/config.toml` with documented examples.
# Default: "../{{ main_worktree }}.{{ branch }}"
path-template = "../{{ main_worktree }}.{{ branch }}"
-# LLM commit message generation
+# LLM commit message generation (see /llm-commits/)
[commit-generation]
command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
+args = ["-m", "claude-haiku-4.5"]
# Per-project command approvals (auto-populated)
[approved-commands."my-project"]
diff --git a/docs/content/intro.md b/docs/content/intro.md
index 10ff031aa..80b104fed 100644
--- a/docs/content/intro.md
+++ b/docs/content/intro.md
@@ -12,6 +12,6 @@ Worktrunk is a CLI for Git worktree management, designed for parallel AI agent w
We recommend:
- **Start with Worktrunk as a simpler & better `git worktree`**: create, navigate, list, and clean up git worktrees with ease
-- **Later use the more advanced features if they resonate**: [LLM commit messages](/configuration/#llm-commit-messages), [local merging with CI-like checks](/concepts/#local-merging-with-wt-merge), [fzf-like worktree picker](/commands/#wt-select), [Claude Code integration](/advanced/#claude-code-integration), and more
+- **Later use the more advanced features if they resonate**: [LLM commit messages](/llm-commits/), [local merging with CI-like checks](/concepts/#local-merging-with-wt-merge), [fzf-like worktree picker](/commands/#wt-select), [Claude Code integration](/advanced/#claude-code-integration), and more
Ready? Head to the [Quick Start](/quickstart/).
diff --git a/docs/content/llm-commits.md b/docs/content/llm-commits.md
new file mode 100644
index 000000000..80433faa0
--- /dev/null
+++ b/docs/content/llm-commits.md
@@ -0,0 +1,214 @@
++++
+title = "LLM Commit Messages"
+weight = 5
++++
+
+Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with `wt merge` and `wt step commit`.
+
+## Setup
+
+### Install llm
+
+[llm](https://llm.datasette.io/) from Simon Willison is recommended:
+
+```bash
+$ uv tool install -U llm
+```
+
+### Configure an API key
+
+For Claude (recommended):
+
+```bash
+$ llm install llm-anthropic
+$ llm keys set anthropic
+```
+
+For OpenAI:
+
+```bash
+$ llm keys set openai
+```
+
+### Add to user config
+
+Create the config file if it doesn't exist:
+
+```bash
+$ wt config create
+```
+
+Then add the commit generation settings to `~/.config/worktrunk/config.toml`:
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4.5"]
+```
+
+Or for OpenAI:
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "gpt-4o-mini"]
+```
+
+## Two generation modes
+
+Worktrunk has two LLM generation functions, each with its own template:
+
+| Mode | Analyzes | Template | Used by |
+|------|----------|----------|---------|
+| **Commit** | Git diff (staged changes) | `template` | `wt step commit`, `wt merge --no-squash` (when dirty) |
+| **Squash** | Commit subjects (message titles) | `squash-template` | `wt step squash`, `wt merge` (default) |
+
+The key difference: commit mode sees *what changed* (diffs), squash mode sees *what was already said* (commit messages).
+
+## Usage
+
+### wt merge (default behavior)
+
+By default, `wt merge` squashes all commits on the branch into one. Any uncommitted changes are staged and included in the squash. The commit message is generated using **squash mode** (analyzing commit subjects, not diffs):
+
+```bash
+$ wt merge
+🔄 Squashing 3 commits into a single commit (5 files, +48)...
+🔄 Generating squash commit message...
+ feat(auth): Implement JWT authentication system
+ ...
+```
+
+### wt merge --no-squash
+
+<!-- TODO: This example only shows committing uncommitted changes. Add an example
+ that shows multiple preserved commits being rebased onto the target branch,
+ which is the main point of --no-squash. -->
+
+With `--no-squash`, individual commits are preserved and rebased onto the target branch. If there are uncommitted changes, they're committed first using **commit mode**:
+
+```bash
+$ wt merge --no-squash
+🔄 Generating commit message and committing changes... (2 files, +15)
+ fix: Handle edge case in config parser
+✅ Committed changes @ a1b2c3d
+🔄 Rebasing onto main...
+```
+
+If there are no uncommitted changes, the commits are rebased as-is without generating any new messages.
+
+### wt step commit
+
+Commits staged changes using **commit mode**:
+
+```bash
+$ wt step commit
+```
+
+### wt step squash
+
+Squashes commits on the current branch using **squash mode**:
+
+```bash
+$ wt step squash
+```
+
+## Prompt templates
+
+Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like syntax) to build prompts. There are sensible defaults, but templates are fully customizable.
+
+### Template variables
+
+**Commit template** (analyzes diffs):
+
+| Variable | Description |
+|----------|-------------|
+| `{{ git_diff }}` | The staged diff |
+| `{{ branch }}` | Current branch name |
+| `{{ recent_commits }}` | List of recent commit subjects (for style reference) |
+| `{{ repo }}` | Repository name |
+
+**Squash template** (analyzes commit messages):
+
+| Variable | Description |
+|----------|-------------|
+| `{{ commits }}` | List of commit messages being squashed (chronological order) |
+| `{{ target_branch }}` | Branch being merged into |
+| `{{ branch }}` | Current branch name |
+| `{{ repo }}` | Repository name |
+
+### Custom templates
+
+Override the defaults with inline templates or external files:
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4.5"]
+
+# Commit mode template (analyzes diffs)
+template = """
+Write a commit message for this diff. One line, under 50 chars.
+
+Branch: {{ branch }}
+Diff:
+{{ git_diff }}
+"""
+
+# Squash mode template (analyzes commit messages)
+squash-template = """
+Combine these {{ commits | length }} commits into one message:
+{% for c in commits %}
+- {{ c }}
+{% endfor %}
+"""
+```
+
+Or load templates from files (supports `~` expansion):
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4.5"]
+
+# Load from files instead
+template-file = "~/.config/worktrunk/commit-template.txt"
+squash-template-file = "~/.config/worktrunk/squash-template.txt"
+```
+
+### Template syntax
+
+Templates use [minijinja](https://docs.rs/minijinja/latest/minijinja/syntax/index.html), which supports:
+
+- **Variables**: `{{ branch }}`, `{{ repo | upper }}`
+- **Filters**: `{{ commits | length }}`, `{{ repo | upper }}`
+- **Conditionals**: `{% if recent_commits %}...{% endif %}`
+- **Loops**: `{% for c in commits %}{{ c }}{% endfor %}`
+- **Loop variables**: `{{ loop.index }}`, `{{ loop.length }}`
+- **Whitespace control**: `{%- ... -%}` strips surrounding whitespace
+
+See `wt config create --help` for the full default templates.
+
+## Alternative tools
+
+Any command that reads a prompt from stdin and outputs a commit message works:
+
+```toml
+# aichat
+[commit-generation]
+command = "aichat"
+args = ["-m", "claude:claude-3-5-haiku-latest"]
+
+# Custom script
+[commit-generation]
+command = "./scripts/generate-commit.sh"
+```
+
+## Fallback behavior
+
+When no LLM is configured, worktrunk uses deterministic fallback messages:
+
+- **Commit mode** generates a message based on changed filenames (e.g., "Changes to auth.rs & config.rs")
+- **Squash mode** generates a message listing the squashed commits
+
+Resources: [llm documentation](https://llm.datasette.io/) | [aichat](https://github.com/sigoden/aichat)
diff --git a/docs/content/quickstart.md b/docs/content/quickstart.md
index 04ae0d260..243897c7f 100644
--- a/docs/content/quickstart.md
+++ b/docs/content/quickstart.md
@@ -83,4 +83,4 @@ Worktrunk checks if your changes are already on main before deleting the branch.
- Understand [why worktrees matter](/concepts/) and how Worktrunk improves on plain git
- Set up [project hooks](/hooks/) for automated setup
-- Use [LLM commit messages](/configuration/#llm-commit-messages) for auto-generated commits
+- Use [LLM commit messages](/llm-commits/) for auto-generated commits