Skip to content

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

docs: name the file every config sample belongs in (#4173)

Maximilian Roosaf9276d4d399
diff --git a/docs/public/.well-known/agent-skills/index.json b/docs/public/.well-known/agent-skills/index.json
index 39f3a328b..24264fd87 100644
--- a/docs/public/.well-known/agent-skills/index.json
+++ b/docs/public/.well-known/agent-skills/index.json
@@ -6,7 +6,7 @@
"type": "skill-md",
"description": "Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when working out which worktree a `wt` command will act on, or reaching for the global `-C <path>` to target one; editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.",
"url": "./worktrunk/SKILL.md",
- "digest": "sha256:1b69b7e3e6fcb3dcedec6f58a633ff8ac543002f5aeb365f9686634bf5b89d5b"
+ "digest": "sha256:29612987f27458c6a9ca7724b800679bdb8c1e84652c75acc4e76589684559e0"
}
]
}
diff --git a/docs/src/content/docs/claude-code.md b/docs/src/content/docs/claude-code.md
index 55329d335..bb261b230 100644
--- a/docs/src/content/docs/claude-code.md
+++ b/docs/src/content/docs/claude-code.md
@@ -164,7 +164,7 @@ Worktree state comes from the same cells [`wt list`](/list/) renders; Claude Cod
Add to `~/.claude/settings.json`:
-```json
+```json title="~/.claude/settings.json"
{
"statusLine": {
"type": "command",
diff --git a/docs/src/content/docs/config.md b/docs/src/content/docs/config.md
index d40b83e04..5cd46eab0 100644
--- a/docs/src/content/docs/config.md
+++ b/docs/src/content/docs/config.md
@@ -1322,6 +1322,7 @@ $ wt config state vars set env=production --branch=main
Variables are available in [hook templates](/hook/#template-variables) as `{{ vars.<key> }}`. Use the `default` filter for keys that may not be set:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.port | default('3000') }}"
```
@@ -1332,6 +1333,7 @@ JSON object and array values support dot access:
$ wt config state vars set config='{"port": 3000, "debug": true}'
```
```toml
+# .config/wt.toml
[post-start]
dev = "npm start -- --port {{ vars.config.port }}"
```
diff --git a/docs/src/content/docs/extending.md b/docs/src/content/docs/extending.md
index 1ab6cc74d..dd3f417d7 100644
--- a/docs/src/content/docs/extending.md
+++ b/docs/src/content/docs/extending.md
@@ -27,6 +27,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](/
Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](/hook/#hook-types) maps each hook to its timing and typical uses.
```toml
+# .config/wt.toml
[pre-start]
deps = "npm ci"
@@ -41,9 +42,10 @@ See [`wt hook`](/hook/) for the full reference and built-in recipes (dev server
## Aliases
-Aliases are configured under `[aliases]`:
+Aliases are configured under `[aliases]`, in project or user config:
```toml
+# .config/wt.toml
[aliases]
deploy = "fly deploy --config=fly.{{ env }}.toml --app=myproject-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
@@ -68,6 +70,7 @@ Alias templates add `{{ args }}` for positional CLI arguments. Operation-context
`{{ args }}` renders as a space-joined, shell-escaped string, ready to splice into a command:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
s = "wt switch {{ args }}"
```
@@ -100,6 +103,7 @@ wt config alias dry-run deploy -- --env=staging
`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](/hook/#hook-forms): blocks run in order, keys within a block run concurrently, and a step failure aborts the remainder.
```toml
+# .config/wt.toml
[[aliases.release]]
test = "cargo test"
@@ -117,31 +121,25 @@ Every step sees the same `{{ args }}` and bound variables. `wt release -- --dry-
`wt switch`, `wt merge` (when it leaves the removed source), and `wt remove` of the current worktree change the parent shell's directory even when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so `cd`, `export`, and similar commands only affect that subshell.
-### Deferring expansion to a nested `wt` command
-
-A `wt step for-each` alias that prints the same branch in every worktree is rendering `{{ branch }}` too early. An alias body renders once at dispatch, in the invoking worktree, so a bare `{{ branch }}` is baked to that worktree's branch before for-each iterates. (`wt config alias dry-run <name>` shows the rendered body, with the value already baked in.)
+### Nesting templates
-`{% raw %}…{% endraw %}` defers the variable: it survives the dispatch render as a literal `{{ branch }}`, and for-each expands it per worktree. One catch for `for-each`: the deferred `{{ branch }}` has spaces, so the alias body's `sh -c` splits it into `{{`, `branch`, `}}` before for-each sees it (`Failed to expand for-each argument: syntax error`). Give for-each its own `sh -c '…'` to keep the value one token:
-
-```toml
-[aliases]
-show-branches = "wt step for-each -- sh -c 'echo {% raw %}{{ branch }}{% endraw %}'"
-```
-
-`wt show-branches` prints each worktree's own branch.
-
-`wt switch --execute` defers the same way. `-x` names the program and arguments after `--` stay separate, so quote the deferred template as one alias-body token. Here `{{ worktree_path }}` expands against the worktree being created, not the one the alias ran from:
+An alias that calls a `wt` command may want to pass it a template for that command to expand — each worktree's own branch, or the worktree `wt switch` is about to create:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
+show-branches = "wt step for-each -- echo '{% raw %}{{ branch }}{% endraw %}'"
echo-target = "wt switch {{ args }} --no-cd --execute echo -- '{% raw %}{{ worktree_path }}{% endraw %}'"
```
-A repo-level variable like `{{ default_branch }}` needs no deferral: it is identical in every worktree, so a bare `{{ default_branch }}` is already correct everywhere.
+An alias body renders once, at dispatch, so a bare `{{ branch }}` would reach the nested command already resolved to the invoking worktree's branch. `{% raw %}…{% endraw %}` passes it through unrendered instead. Quote it — the deferred text contains spaces, and the alias body is a shell command line.
+
+Repo-level variables like `{{ default_branch }}` are identical in every worktree, so they need no deferral.
### Recipe: rebase every worktree onto its upstream
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
up = '''
git fetch --all --prune; wt step for-each -- sh -c '
@@ -156,12 +154,7 @@ git fetch --all --prune; wt step for-each -- sh -c '
`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.
-Two details matter when adapting it:
-
-- `;` after the fetch lets the sweep run even when one remote fails to fetch.
-- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.
-
-The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.
+`--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave conflict markers behind and still exit 0.
### Recipe: move or copy in-progress changes to a new worktree
@@ -191,6 +184,7 @@ To copy instead of move, add `git stash apply --index --quiet` right after the p
`wt config state logs --format=json` emits structured entries (`branch`, `source`, `hook_type`, `name`, `path`). Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
hook-log = '''
tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" --arg kind "{{ kind }}" '
diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.md
index f33c845bf..023dd1c26 100644
--- a/docs/src/content/docs/faq.md
+++ b/docs/src/content/docs/faq.md
@@ -282,7 +282,7 @@ For full details on the detection mechanism, see `wt config state default-branch
## My `for-each` or `--execute` alias prints the same value in every worktree
-The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [deferring expansion to a nested `wt` command](/extending/#deferring-expansion-to-a-nested-wt-command) for how to confirm it and how to defer the variable.
+The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [nesting templates](/extending/#nesting-templates) for how to pass the template through unrendered.
## What system dependencies are required?
diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.md
index f5611ef74..eea2cd004 100644
--- a/docs/src/content/docs/hook.md
+++ b/docs/src/content/docs/hook.md
@@ -75,12 +75,14 @@ Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
```toml
+# .config/wt.toml
pre-start = "npm install"
```
A table is multiple commands that run concurrently:
```toml
+# .config/wt.toml
[post-start]
server = "npm run dev"
watch = "npm run watch"
@@ -89,6 +91,7 @@ watch = "npm run watch"
A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
+# .config/wt.toml
[[post-start]]
install = "npm ci"
@@ -170,6 +173,7 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the
Undefined variables error — use conditionals or defaults for optional behavior:
```toml
+# .config/wt.toml
[pre-start]
# Rebase onto upstream if tracking a remote branch (e.g., wt switch --create feature --base origin/feature)
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
@@ -182,6 +186,7 @@ Run any hook-firing command with `-v` to see the resolved variables for the actu
Variables use dot access and the `default` filter for missing keys. JSON object/array values are parsed automatically, so `{{ vars.config.port }}` works when the value is `{"port": 3000}`:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.config.port | default('3000') }}"
```
@@ -206,6 +211,7 @@ The `sanitize_db` filter produces database-safe identifiers — lowercase alphan
The `hash` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
```toml
+# ~/.config/worktrunk/config.toml
# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
```
@@ -213,6 +219,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash
The `dirname` and `basename` filters traverse paths. They're useful for bare repos in a hidden directory like `myproject/.git`, where `{{ repo }}` resolves to `.git`:
```toml
+# ~/.config/worktrunk/config.toml
# Place worktrees as siblings of the bare repo, named `<wrapper>.<branch>`
worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ branch | sanitize }}"
```
@@ -220,6 +227,7 @@ worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ bran
The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
+# .config/wt.toml
[post-start]
dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
@@ -227,7 +235,9 @@ dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port
Hash any string, including concatenations:
```toml
+# .config/wt.toml
# Unique port per repo+branch combination
+[post-start]
dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
@@ -244,6 +254,7 @@ Templates also support functions for dynamic lookups:
The `worktree_path_of_branch` function returns the filesystem path of a worktree given a branch name, or an empty string if no worktree exists for that branch. This is useful for referencing files in other worktrees:
```toml
+# .config/wt.toml
[pre-start]
# Copy config from main worktree
setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
@@ -254,11 +265,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path
Hooks receive all template variables as JSON on stdin, enabling complex logic that templates can't express. Variables that are unset in a template are absent from the JSON too, so read the optional ones with a default — `branch` has none in a detached worktree:
```toml
+# .config/wt.toml
[pre-start]
setup = "python3 scripts/pre-start-setup.py"
```
```python
+# scripts/pre-start-setup.py
import json, sys, subprocess
ctx = json.load(sys.stdin)
if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
@@ -270,6 +283,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
diff --git a/docs/src/content/docs/list.md b/docs/src/content/docs/list.md
index 40bb3f800..0272c0e59 100644
--- a/docs/src/content/docs/list.md
+++ b/docs/src/content/docs/list.md
@@ -141,6 +141,7 @@ Reuses the [`commit.generation`](/config/#commit) command — the same LLM that
Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — `{{ vars.* }}`, stored with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) — useful for tracking what each of many (often agent-driven) branches is for:
```toml
+# ~/.config/worktrunk/config.toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"
```
diff --git a/docs/src/content/docs/llm-commits.md b/docs/src/content/docs/llm-commits.md
index b399cb11e..e73408147 100644
--- a/docs/src/content/docs/llm-commits.md
+++ b/docs/src/content/docs/llm-commits.md
@@ -21,6 +21,7 @@ Any command that reads a prompt from stdin and outputs a commit message works. A
### Claude Code
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```
@@ -30,6 +31,7 @@ command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haik
### Codex
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "codex exec -m gpt-5.6-luna -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
```
@@ -131,6 +133,7 @@ Summaries appear in:
Enable in user config:
```toml
+# ~/.config/worktrunk/config.toml
[list]
summary = true
```
@@ -146,6 +149,7 @@ Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like sy
Override the defaults with inline templates:
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "llm -m claude-haiku-4.5"
diff --git a/docs/src/content/docs/merge.md b/docs/src/content/docs/merge.md
index 5949c5018..522a542ec 100644
--- a/docs/src/content/docs/merge.md
+++ b/docs/src/content/docs/merge.md
@@ -99,6 +99,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
+# .config/wt.toml
[[pre-merge]]
test = "cargo test"
lint = "cargo clippy"
diff --git a/docs/src/content/docs/step.md b/docs/src/content/docs/step.md
index a0dcc3353..629fbda6b 100644
--- a/docs/src/content/docs/step.md
+++ b/docs/src/content/docs/step.md
@@ -138,6 +138,7 @@ $ wt step commit --stage=tracked
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -219,6 +220,7 @@ $ wt step squash --stage=none
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -482,6 +484,7 @@ target/
After `.worktreeinclude` selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:
```toml
+# ~/.config/worktrunk/config.toml
[step.copy-ignored]
exclude = [".cache/", ".turbo/"]
```
@@ -529,6 +532,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
```toml
+# .config/wt.toml
[pre-start]
deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
@@ -695,7 +699,7 @@ Variables substitute into each argv element before exec. See [`wt hook` template
$ wt step for-each -- echo 'Branch: {{ branch }}'
```
-Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [deferring expansion in an alias](/extending/#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.
+Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [nesting templates](/extending/#nesting-templates) shows how to keep a variable per-worktree.
### Examples
diff --git a/docs/src/content/docs/switch.md b/docs/src/content/docs/switch.md
index be72f7d1b..e70cc3e5f 100644
--- a/docs/src/content/docs/switch.md
+++ b/docs/src/content/docs/switch.md
@@ -127,6 +127,7 @@ The comparison base is the merge-base with the default branch, or with its upstr
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
```toml
+# ~/.config/worktrunk/config.toml
[switch.picker]
pager = "delta --paging=never --width=$COLUMNS"
```
diff --git a/docs/src/content/docs/tips-patterns.md b/docs/src/content/docs/tips-patterns.md
index ff3c0a83a..9893b02ab 100644
--- a/docs/src/content/docs/tips-patterns.md
+++ b/docs/src/content/docs/tips-patterns.md
@@ -151,6 +151,7 @@ See [`wt config state vars`](/config/#wt-config-state-vars) for storage format,
Reference Taskfile/Justfile/Makefile in hooks:
```toml
+# .config/wt.toml
[pre-start]
"setup" = "task install"
@@ -163,6 +164,7 @@ Reference Taskfile/Justfile/Makefile in hooks:
Split checks across hook types — quick feedback before each commit, expensive suites before merge:
```toml
+# .config/wt.toml
[[pre-commit]]
lint = "npm run lint"
typecheck = "npm run typecheck"
@@ -179,6 +181,7 @@ build = "npm run build"
Branch on `{{ target }}` to vary behavior per merge destination — for example, deploying to production from `main` and staging from a release branch:
```toml
+# .config/wt.toml
post-merge = """
if [ {{ target }} = main ]; then
npm run deploy:production
@@ -231,6 +234,7 @@ $ wt list
Each worktree can have its own isolated database. A pipeline sets up names and ports as [vars](/config/#wt-config-state-vars), then later steps and hooks reference them:
```toml
+# .config/wt.toml
[[post-start]]
set-vars = """
wt config state vars set \
@@ -270,6 +274,7 @@ To scope environment variables to a worktree — a tool's package path, a profil
**direnv** — commit `.envrc` at the repo root:
```sh
+# .envrc
export MY_PACKAGES_PATH="$PWD/.packages"
```
@@ -278,6 +283,7 @@ Run `direnv allow` once per worktree to trust the file ([getting started](https:
**mise** — commit `mise.toml` at the repo root:
```toml
+# mise.toml
[env]
MY_PACKAGES_PATH = "{{ config_root }}/.packages"
```
@@ -291,6 +297,7 @@ Both set real environment variables in the shell session, so every child process
Use [`wt step copy-ignored`](/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
@@ -298,6 +305,7 @@ copy = "wt step copy-ignored"
When another hook depends on the copy — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages — sequence them with a `[[post-start]]` pipeline:
```toml
+# .config/wt.toml
[[post-start]]
copy = "wt step copy-ignored"
@@ -460,7 +468,7 @@ This lets one agent session hand off work to another that runs in the background
The [worktrunk skill](/claude-code/) includes guidance for Claude Code (and other agent CLIs that load it) to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to your project instructions (`CLAUDE.md` or `AGENTS.md`):
-```markdown
+```markdown title="CLAUDE.md"
When I ask you to spawn parallel worktrees, use the agent handoff pattern
from the worktrunk skill.
```
diff --git a/plugins/worktrunk/skills/worktrunk/SKILL.md b/plugins/worktrunk/skills/worktrunk/SKILL.md
index 8431cc473..ef0796921 100644
--- a/plugins/worktrunk/skills/worktrunk/SKILL.md
+++ b/plugins/worktrunk/skills/worktrunk/SKILL.md
@@ -100,7 +100,7 @@ Test with `wt switch --create test-hooks`.
- Create a `wt` alias → `reference/extending.md#aliases`
- Run a command in every worktree → `reference/step.md#wt-step-for-each`
- Rebase every worktree (up-style) → `reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream`
-- Defer a template variable to a nested `wt` command → `reference/extending.md#deferring-expansion-to-a-nested-wt-command`
+- Pass a template to a nested `wt` command → `reference/extending.md#nesting-templates`
## Key commands
diff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
index 3ee7b27c8..b574ee8c9 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/claude-code.md
@@ -148,7 +148,7 @@ Worktree state comes from the same cells [`wt list`](https://worktrunk.dev/list/
Add to `~/.claude/settings.json`:
-```json
+```json title="~/.claude/settings.json"
{
"statusLine": {
"type": "command",
diff --git a/plugins/worktrunk/skills/worktrunk/reference/config.md b/plugins/worktrunk/skills/worktrunk/reference/config.md
index fae65d742..043b37b60 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/config.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/config.md
@@ -1314,6 +1314,7 @@ $ wt config state vars set env=production --branch=main
Variables are available in [hook templates](https://worktrunk.dev/hook/#template-variables) as `{{ vars.<key> }}`. Use the `default` filter for keys that may not be set:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.port | default('3000') }}"
```
@@ -1324,6 +1325,7 @@ JSON object and array values support dot access:
$ wt config state vars set config='{"port": 3000, "debug": true}'
```
```toml
+# .config/wt.toml
[post-start]
dev = "npm start -- --port {{ vars.config.port }}"
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/extending.md b/plugins/worktrunk/skills/worktrunk/reference/extending.md
index c688d4654..7d5a44eeb 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/extending.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/extending.md
@@ -23,6 +23,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](h
Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](https://worktrunk.dev/hook/#hook-types) maps each hook to its timing and typical uses.
```toml
+# .config/wt.toml
[pre-start]
deps = "npm ci"
@@ -37,9 +38,10 @@ See [`wt hook`](https://worktrunk.dev/hook/) for the full reference and built-in
## Aliases
-Aliases are configured under `[aliases]`:
+Aliases are configured under `[aliases]`, in project or user config:
```toml
+# .config/wt.toml
[aliases]
deploy = "fly deploy --config=fly.{{ env }}.toml --app=myproject-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
@@ -64,6 +66,7 @@ Alias templates add `{{ args }}` for positional CLI arguments. Operation-context
`{{ args }}` renders as a space-joined, shell-escaped string, ready to splice into a command:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
s = "wt switch {{ args }}"
```
@@ -96,6 +99,7 @@ wt config alias dry-run deploy -- --env=staging
`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](https://worktrunk.dev/hook/#hook-forms): blocks run in order, keys within a block run concurrently, and a step failure aborts the remainder.
```toml
+# .config/wt.toml
[[aliases.release]]
test = "cargo test"
@@ -113,31 +117,25 @@ Every step sees the same `{{ args }}` and bound variables. `wt release -- --dry-
`wt switch`, `wt merge` (when it leaves the removed source), and `wt remove` of the current worktree change the parent shell's directory even when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so `cd`, `export`, and similar commands only affect that subshell.
-### Deferring expansion to a nested `wt` command
-
-A `wt step for-each` alias that prints the same branch in every worktree is rendering `{{ branch }}` too early. An alias body renders once at dispatch, in the invoking worktree, so a bare `{{ branch }}` is baked to that worktree's branch before for-each iterates. (`wt config alias dry-run <name>` shows the rendered body, with the value already baked in.)
+### Nesting templates
-`{% raw %}…{% endraw %}` defers the variable: it survives the dispatch render as a literal `{{ branch }}`, and for-each expands it per worktree. One catch for `for-each`: the deferred `{{ branch }}` has spaces, so the alias body's `sh -c` splits it into `{{`, `branch`, `}}` before for-each sees it (`Failed to expand for-each argument: syntax error`). Give for-each its own `sh -c '…'` to keep the value one token:
-
-```toml
-[aliases]
-show-branches = "wt step for-each -- sh -c 'echo {% raw %}{{ branch }}{% endraw %}'"
-```
-
-`wt show-branches` prints each worktree's own branch.
-
-`wt switch --execute` defers the same way. `-x` names the program and arguments after `--` stay separate, so quote the deferred template as one alias-body token. Here `{{ worktree_path }}` expands against the worktree being created, not the one the alias ran from:
+An alias that calls a `wt` command may want to pass it a template for that command to expand — each worktree's own branch, or the worktree `wt switch` is about to create:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
+show-branches = "wt step for-each -- echo '{% raw %}{{ branch }}{% endraw %}'"
echo-target = "wt switch {{ args }} --no-cd --execute echo -- '{% raw %}{{ worktree_path }}{% endraw %}'"
```
-A repo-level variable like `{{ default_branch }}` needs no deferral: it is identical in every worktree, so a bare `{{ default_branch }}` is already correct everywhere.
+An alias body renders once, at dispatch, so a bare `{{ branch }}` would reach the nested command already resolved to the invoking worktree's branch. `{% raw %}…{% endraw %}` passes it through unrendered instead. Quote it — the deferred text contains spaces, and the alias body is a shell command line.
+
+Repo-level variables like `{{ default_branch }}` are identical in every worktree, so they need no deferral.
### Recipe: rebase every worktree onto its upstream
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
up = '''
git fetch --all --prune; wt step for-each -- sh -c '
@@ -152,12 +150,7 @@ git fetch --all --prune; wt step for-each -- sh -c '
`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.
-Two details matter when adapting it:
-
-- `;` after the fetch lets the sweep run even when one remote fails to fetch.
-- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.
-
-The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.
+`--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave conflict markers behind and still exit 0.
### Recipe: move or copy in-progress changes to a new worktree
@@ -187,6 +180,7 @@ To copy instead of move, add `git stash apply --index --quiet` right after the p
`wt config state logs --format=json` emits structured entries (`branch`, `source`, `hook_type`, `name`, `path`). Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
hook-log = '''
tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" --arg kind "{{ kind }}" '
diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.md
index 1af900ec4..e3e8e4d4a 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md
@@ -278,7 +278,7 @@ For full details on the detection mechanism, see `wt config state default-branch
## My `for-each` or `--execute` alias prints the same value in every worktree
-The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [deferring expansion to a nested `wt` command](https://worktrunk.dev/extending/#deferring-expansion-to-a-nested-wt-command) for how to confirm it and how to defer the variable.
+The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [nesting templates](https://worktrunk.dev/extending/#nesting-templates) for how to pass the template through unrendered.
## What system dependencies are required?
diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.md
index e3e71c131..6074249c1 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md
@@ -69,12 +69,14 @@ Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
```toml
+# .config/wt.toml
pre-start = "npm install"
```
A table is multiple commands that run concurrently:
```toml
+# .config/wt.toml
[post-start]
server = "npm run dev"
watch = "npm run watch"
@@ -83,6 +85,7 @@ watch = "npm run watch"
A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
+# .config/wt.toml
[[post-start]]
install = "npm ci"
@@ -164,6 +167,7 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the
Undefined variables error — use conditionals or defaults for optional behavior:
```toml
+# .config/wt.toml
[pre-start]
# Rebase onto upstream if tracking a remote branch (e.g., wt switch --create feature --base origin/feature)
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
@@ -176,6 +180,7 @@ Run any hook-firing command with `-v` to see the resolved variables for the actu
Variables use dot access and the `default` filter for missing keys. JSON object/array values are parsed automatically, so `{{ vars.config.port }}` works when the value is `{"port": 3000}`:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.config.port | default('3000') }}"
```
@@ -200,6 +205,7 @@ The `sanitize_db` filter produces database-safe identifiers — lowercase alphan
The `hash` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
```toml
+# ~/.config/worktrunk/config.toml
# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
```
@@ -207,6 +213,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash
The `dirname` and `basename` filters traverse paths. They're useful for bare repos in a hidden directory like `myproject/.git`, where `{{ repo }}` resolves to `.git`:
```toml
+# ~/.config/worktrunk/config.toml
# Place worktrees as siblings of the bare repo, named `<wrapper>.<branch>`
worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ branch | sanitize }}"
```
@@ -214,6 +221,7 @@ worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ bran
The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
+# .config/wt.toml
[post-start]
dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
@@ -221,7 +229,9 @@ dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port
Hash any string, including concatenations:
```toml
+# .config/wt.toml
# Unique port per repo+branch combination
+[post-start]
dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
@@ -238,6 +248,7 @@ Templates also support functions for dynamic lookups:
The `worktree_path_of_branch` function returns the filesystem path of a worktree given a branch name, or an empty string if no worktree exists for that branch. This is useful for referencing files in other worktrees:
```toml
+# .config/wt.toml
[pre-start]
# Copy config from main worktree
setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
@@ -248,11 +259,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path
Hooks receive all template variables as JSON on stdin, enabling complex logic that templates can't express. Variables that are unset in a template are absent from the JSON too, so read the optional ones with a default — `branch` has none in a detached worktree:
```toml
+# .config/wt.toml
[pre-start]
setup = "python3 scripts/pre-start-setup.py"
```
```python
+# scripts/pre-start-setup.py
import json, sys, subprocess
ctx = json.load(sys.stdin)
if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
@@ -264,6 +277,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.md
index f25a56bcb..3588121d4 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/list.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md
@@ -125,6 +125,7 @@ Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command
Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — `{{ vars.* }}`, stored with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) — useful for tracking what each of many (often agent-driven) branches is for:
```toml
+# ~/.config/worktrunk/config.toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md b/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
index cc451bb17..1094399b4 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/llm-commits.md
@@ -9,6 +9,7 @@ Any command that reads a prompt from stdin and outputs a commit message works. A
### Claude Code
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```
@@ -18,6 +19,7 @@ command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haik
### Codex
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "codex exec -m gpt-5.6-luna -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
```
@@ -107,6 +109,7 @@ Summaries appear in:
Enable in user config:
```toml
+# ~/.config/worktrunk/config.toml
[list]
summary = true
```
@@ -122,6 +125,7 @@ Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like sy
Override the defaults with inline templates:
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "llm -m claude-haiku-4.5"
diff --git a/plugins/worktrunk/skills/worktrunk/reference/merge.md b/plugins/worktrunk/skills/worktrunk/reference/merge.md
index fb456e829..28affc94d 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/merge.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/merge.md
@@ -85,6 +85,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
+# .config/wt.toml
[[pre-merge]]
test = "cargo test"
lint = "cargo clippy"
diff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.md
index b8770dabb..fb359164c 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/step.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md
@@ -126,6 +126,7 @@ $ wt step commit --stage=tracked
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -207,6 +208,7 @@ $ wt step squash --stage=none
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -470,6 +472,7 @@ target/
After `.worktreeinclude` selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:
```toml
+# ~/.config/worktrunk/config.toml
[step.copy-ignored]
exclude = [".cache/", ".turbo/"]
```
@@ -517,6 +520,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
```toml
+# .config/wt.toml
[pre-start]
deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
@@ -683,7 +687,7 @@ Variables substitute into each argv element before exec. See [`wt hook` template
$ wt step for-each -- echo 'Branch: {{ branch }}'
```
-Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [deferring expansion in an alias](https://worktrunk.dev/extending/#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.
+Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [nesting templates](https://worktrunk.dev/extending/#nesting-templates) shows how to keep a variable per-worktree.
### Examples
diff --git a/plugins/worktrunk/skills/worktrunk/reference/switch.md b/plugins/worktrunk/skills/worktrunk/reference/switch.md
index eac1f9273..bcbeefc87 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/switch.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/switch.md
@@ -105,6 +105,7 @@ The comparison base is the merge-base with the default branch, or with its upstr
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
```toml
+# ~/.config/worktrunk/config.toml
[switch.picker]
pager = "delta --paging=never --width=$COLUMNS"
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
index 4a6a4cdeb..160968f61 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/tips-patterns.md
@@ -147,6 +147,7 @@ See [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars)
Reference Taskfile/Justfile/Makefile in hooks:
```toml
+# .config/wt.toml
[pre-start]
"setup" = "task install"
@@ -159,6 +160,7 @@ Reference Taskfile/Justfile/Makefile in hooks:
Split checks across hook types — quick feedback before each commit, expensive suites before merge:
```toml
+# .config/wt.toml
[[pre-commit]]
lint = "npm run lint"
typecheck = "npm run typecheck"
@@ -175,6 +177,7 @@ build = "npm run build"
Branch on `{{ target }}` to vary behavior per merge destination — for example, deploying to production from `main` and staging from a release branch:
```toml
+# .config/wt.toml
post-merge = """
if [ {{ target }} = main ]; then
npm run deploy:production
@@ -223,6 +226,7 @@ $ wt list
Each worktree can have its own isolated database. A pipeline sets up names and ports as [vars](https://worktrunk.dev/config/#wt-config-state-vars), then later steps and hooks reference them:
```toml
+# .config/wt.toml
[[post-start]]
set-vars = """
wt config state vars set \
@@ -262,6 +266,7 @@ To scope environment variables to a worktree — a tool's package path, a profil
**direnv** — commit `.envrc` at the repo root:
```sh
+# .envrc
export MY_PACKAGES_PATH="$PWD/.packages"
```
@@ -270,6 +275,7 @@ Run `direnv allow` once per worktree to trust the file ([getting started](https:
**mise** — commit `mise.toml` at the repo root:
```toml
+# mise.toml
[env]
MY_PACKAGES_PATH = "{{ config_root }}/.packages"
```
@@ -283,6 +289,7 @@ Both set real environment variables in the shell session, so every child process
Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
@@ -290,6 +297,7 @@ copy = "wt step copy-ignored"
When another hook depends on the copy — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages — sequence them with a `[[post-start]]` pipeline:
```toml
+# .config/wt.toml
[[post-start]]
copy = "wt step copy-ignored"
@@ -452,7 +460,7 @@ This lets one agent session hand off work to another that runs in the background
The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code (and other agent CLIs that load it) to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to your project instructions (`CLAUDE.md` or `AGENTS.md`):
-```markdown
+```markdown title="CLAUDE.md"
When I ask you to spawn parallel worktrees, use the agent handoff pattern
from the worktrunk skill.
```
diff --git a/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md b/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
index 82527b3ec..7ca50ad7e 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md
@@ -81,7 +81,7 @@ post-start = "npm run build"
### A `for-each` or `--execute` alias uses the same value in every worktree
-The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See `reference/extending.md#deferring-expansion-to-a-nested-wt-command` for how to confirm it and how to defer the variable.
+The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See `reference/extending.md#nesting-templates` for how to pass the template through unrendered.
## List
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index 8431cc473..ef0796921 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -100,7 +100,7 @@ Test with `wt switch --create test-hooks`.
- Create a `wt` alias → `reference/extending.md#aliases`
- Run a command in every worktree → `reference/step.md#wt-step-for-each`
- Rebase every worktree (up-style) → `reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream`
-- Defer a template variable to a nested `wt` command → `reference/extending.md#deferring-expansion-to-a-nested-wt-command`
+- Pass a template to a nested `wt` command → `reference/extending.md#nesting-templates`
## Key commands
diff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.md
index 3ee7b27c8..b574ee8c9 100644
--- a/skills/worktrunk/reference/claude-code.md
+++ b/skills/worktrunk/reference/claude-code.md
@@ -148,7 +148,7 @@ Worktree state comes from the same cells [`wt list`](https://worktrunk.dev/list/
Add to `~/.claude/settings.json`:
-```json
+```json title="~/.claude/settings.json"
{
"statusLine": {
"type": "command",
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index fae65d742..043b37b60 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -1314,6 +1314,7 @@ $ wt config state vars set env=production --branch=main
Variables are available in [hook templates](https://worktrunk.dev/hook/#template-variables) as `{{ vars.<key> }}`. Use the `default` filter for keys that may not be set:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.port | default('3000') }}"
```
@@ -1324,6 +1325,7 @@ JSON object and array values support dot access:
$ wt config state vars set config='{"port": 3000, "debug": true}'
```
```toml
+# .config/wt.toml
[post-start]
dev = "npm start -- --port {{ vars.config.port }}"
```
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index c688d4654..7d5a44eeb 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -23,6 +23,7 @@ Hooks and aliases live in the same TOML config and share the [template engine](h
Ten hooks cover five lifecycle events — switch, start, commit, merge, remove — each with a blocking `pre-` variant (failure aborts the operation) and a background `post-` variant. [`wt hook`](https://worktrunk.dev/hook/#hook-types) maps each hook to its timing and typical uses.
```toml
+# .config/wt.toml
[pre-start]
deps = "npm ci"
@@ -37,9 +38,10 @@ See [`wt hook`](https://worktrunk.dev/hook/) for the full reference and built-in
## Aliases
-Aliases are configured under `[aliases]`:
+Aliases are configured under `[aliases]`, in project or user config:
```toml
+# .config/wt.toml
[aliases]
deploy = "fly deploy --config=fly.{{ env }}.toml --app=myproject-{{ branch }}"
open = "open http://localhost:{{ branch | hash_port }}"
@@ -64,6 +66,7 @@ Alias templates add `{{ args }}` for positional CLI arguments. Operation-context
`{{ args }}` renders as a space-joined, shell-escaped string, ready to splice into a command:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
s = "wt switch {{ args }}"
```
@@ -96,6 +99,7 @@ wt config alias dry-run deploy -- --env=staging
`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](https://worktrunk.dev/hook/#hook-forms): blocks run in order, keys within a block run concurrently, and a step failure aborts the remainder.
```toml
+# .config/wt.toml
[[aliases.release]]
test = "cargo test"
@@ -113,31 +117,25 @@ Every step sees the same `{{ args }}` and bound variables. `wt release -- --dry-
`wt switch`, `wt merge` (when it leaves the removed source), and `wt remove` of the current worktree change the parent shell's directory even when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so `cd`, `export`, and similar commands only affect that subshell.
-### Deferring expansion to a nested `wt` command
-
-A `wt step for-each` alias that prints the same branch in every worktree is rendering `{{ branch }}` too early. An alias body renders once at dispatch, in the invoking worktree, so a bare `{{ branch }}` is baked to that worktree's branch before for-each iterates. (`wt config alias dry-run <name>` shows the rendered body, with the value already baked in.)
+### Nesting templates
-`{% raw %}…{% endraw %}` defers the variable: it survives the dispatch render as a literal `{{ branch }}`, and for-each expands it per worktree. One catch for `for-each`: the deferred `{{ branch }}` has spaces, so the alias body's `sh -c` splits it into `{{`, `branch`, `}}` before for-each sees it (`Failed to expand for-each argument: syntax error`). Give for-each its own `sh -c '…'` to keep the value one token:
-
-```toml
-[aliases]
-show-branches = "wt step for-each -- sh -c 'echo {% raw %}{{ branch }}{% endraw %}'"
-```
-
-`wt show-branches` prints each worktree's own branch.
-
-`wt switch --execute` defers the same way. `-x` names the program and arguments after `--` stay separate, so quote the deferred template as one alias-body token. Here `{{ worktree_path }}` expands against the worktree being created, not the one the alias ran from:
+An alias that calls a `wt` command may want to pass it a template for that command to expand — each worktree's own branch, or the worktree `wt switch` is about to create:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
+show-branches = "wt step for-each -- echo '{% raw %}{{ branch }}{% endraw %}'"
echo-target = "wt switch {{ args }} --no-cd --execute echo -- '{% raw %}{{ worktree_path }}{% endraw %}'"
```
-A repo-level variable like `{{ default_branch }}` needs no deferral: it is identical in every worktree, so a bare `{{ default_branch }}` is already correct everywhere.
+An alias body renders once, at dispatch, so a bare `{{ branch }}` would reach the nested command already resolved to the invoking worktree's branch. `{% raw %}…{% endraw %}` passes it through unrendered instead. Quote it — the deferred text contains spaces, and the alias body is a shell command line.
+
+Repo-level variables like `{{ default_branch }}` are identical in every worktree, so they need no deferral.
### Recipe: rebase every worktree onto its upstream
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
up = '''
git fetch --all --prune; wt step for-each -- sh -c '
@@ -152,12 +150,7 @@ git fetch --all --prune; wt step for-each -- sh -c '
`wt up` fetches every remote, then brings each worktree up to date with its upstream: skip if there is no upstream or a rebase is already in progress, fast-forward if a tracked file is modified or staged, otherwise rebase, aborting on conflict. It rebases onto git-native `@{u}` rather than a `{{ … }}` template, so git resolves each worktree's own upstream and there is nothing to defer.
-Two details matter when adapting it:
-
-- `;` after the fetch lets the sweep run even when one remote fails to fetch.
-- `--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave markers behind and still exit 0.
-
-The sweep exits non-zero only when it leaves a worktree needing attention, which matters when the alias runs as a hook step: a failing step stops the rest of the pipeline.
+`--no-autostash` overrides a global `rebase.autostash` or `merge.autostash`, whose conflicting pop would leave conflict markers behind and still exit 0.
### Recipe: move or copy in-progress changes to a new worktree
@@ -187,6 +180,7 @@ To copy instead of move, add `git stash apply --index --quiet` right after the p
`wt config state logs --format=json` emits structured entries (`branch`, `source`, `hook_type`, `name`, `path`). Pipe through `jq` to resolve one entry, then wrap in an alias for quick access:
```toml
+# ~/.config/worktrunk/config.toml
[aliases]
hook-log = '''
tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | sanitize_hash }}" --arg kind "{{ kind }}" '
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 1af900ec4..e3e8e4d4a 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -278,7 +278,7 @@ For full details on the detection mechanism, see `wt config state default-branch
## My `for-each` or `--execute` alias prints the same value in every worktree
-The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [deferring expansion to a nested `wt` command](https://worktrunk.dev/extending/#deferring-expansion-to-a-nested-wt-command) for how to confirm it and how to defer the variable.
+The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See [nesting templates](https://worktrunk.dev/extending/#nesting-templates) for how to pass the template through unrendered.
## What system dependencies are required?
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index e3e71c131..6074249c1 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -69,12 +69,14 @@ Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
```toml
+# .config/wt.toml
pre-start = "npm install"
```
A table is multiple commands that run concurrently:
```toml
+# .config/wt.toml
[post-start]
server = "npm run dev"
watch = "npm run watch"
@@ -83,6 +85,7 @@ watch = "npm run watch"
A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
+# .config/wt.toml
[[post-start]]
install = "npm ci"
@@ -164,6 +167,7 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the
Undefined variables error — use conditionals or defaults for optional behavior:
```toml
+# .config/wt.toml
[pre-start]
# Rebase onto upstream if tracking a remote branch (e.g., wt switch --create feature --base origin/feature)
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
@@ -176,6 +180,7 @@ Run any hook-firing command with `-v` to see the resolved variables for the actu
Variables use dot access and the `default` filter for missing keys. JSON object/array values are parsed automatically, so `{{ vars.config.port }}` works when the value is `{"port": 3000}`:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.config.port | default('3000') }}"
```
@@ -200,6 +205,7 @@ The `sanitize_db` filter produces database-safe identifiers — lowercase alphan
The `hash` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
```toml
+# ~/.config/worktrunk/config.toml
# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
```
@@ -207,6 +213,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash
The `dirname` and `basename` filters traverse paths. They're useful for bare repos in a hidden directory like `myproject/.git`, where `{{ repo }}` resolves to `.git`:
```toml
+# ~/.config/worktrunk/config.toml
# Place worktrees as siblings of the bare repo, named `<wrapper>.<branch>`
worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ branch | sanitize }}"
```
@@ -214,6 +221,7 @@ worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ bran
The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
+# .config/wt.toml
[post-start]
dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
@@ -221,7 +229,9 @@ dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port
Hash any string, including concatenations:
```toml
+# .config/wt.toml
# Unique port per repo+branch combination
+[post-start]
dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
@@ -238,6 +248,7 @@ Templates also support functions for dynamic lookups:
The `worktree_path_of_branch` function returns the filesystem path of a worktree given a branch name, or an empty string if no worktree exists for that branch. This is useful for referencing files in other worktrees:
```toml
+# .config/wt.toml
[pre-start]
# Copy config from main worktree
setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
@@ -248,11 +259,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path
Hooks receive all template variables as JSON on stdin, enabling complex logic that templates can't express. Variables that are unset in a template are absent from the JSON too, so read the optional ones with a default — `branch` has none in a detached worktree:
```toml
+# .config/wt.toml
[pre-start]
setup = "python3 scripts/pre-start-setup.py"
```
```python
+# scripts/pre-start-setup.py
import json, sys, subprocess
ctx = json.load(sys.stdin)
if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
@@ -264,6 +277,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index f25a56bcb..3588121d4 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -125,6 +125,7 @@ Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command
Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — `{{ vars.* }}`, stored with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) — useful for tracking what each of many (often agent-driven) branches is for:
```toml
+# ~/.config/worktrunk/config.toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"
```
diff --git a/skills/worktrunk/reference/llm-commits.md b/skills/worktrunk/reference/llm-commits.md
index cc451bb17..1094399b4 100644
--- a/skills/worktrunk/reference/llm-commits.md
+++ b/skills/worktrunk/reference/llm-commits.md
@@ -9,6 +9,7 @@ Any command that reads a prompt from stdin and outputs a commit message works. A
### Claude Code
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```
@@ -18,6 +19,7 @@ command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haik
### Codex
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "codex exec -m gpt-5.6-luna -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
```
@@ -107,6 +109,7 @@ Summaries appear in:
Enable in user config:
```toml
+# ~/.config/worktrunk/config.toml
[list]
summary = true
```
@@ -122,6 +125,7 @@ Worktrunk uses [minijinja](https://docs.rs/minijinja/) templates (Jinja2-like sy
Override the defaults with inline templates:
```toml
+# ~/.config/worktrunk/config.toml
[commit.generation]
command = "llm -m claude-haiku-4.5"
diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.md
index fb456e829..28affc94d 100644
--- a/skills/worktrunk/reference/merge.md
+++ b/skills/worktrunk/reference/merge.md
@@ -85,6 +85,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
+# .config/wt.toml
[[pre-merge]]
test = "cargo test"
lint = "cargo clippy"
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index b8770dabb..fb359164c 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -126,6 +126,7 @@ $ wt step commit --stage=tracked
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -207,6 +208,7 @@ $ wt step squash --stage=none
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -470,6 +472,7 @@ target/
After `.worktreeinclude` selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:
```toml
+# ~/.config/worktrunk/config.toml
[step.copy-ignored]
exclude = [".cache/", ".turbo/"]
```
@@ -517,6 +520,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
```toml
+# .config/wt.toml
[pre-start]
deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
@@ -683,7 +687,7 @@ Variables substitute into each argv element before exec. See [`wt hook` template
$ wt step for-each -- echo 'Branch: {{ branch }}'
```
-Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [deferring expansion in an alias](https://worktrunk.dev/extending/#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.
+Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [nesting templates](https://worktrunk.dev/extending/#nesting-templates) shows how to keep a variable per-worktree.
### Examples
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index eac1f9273..bcbeefc87 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -105,6 +105,7 @@ The comparison base is the merge-base with the default branch, or with its upstr
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
```toml
+# ~/.config/worktrunk/config.toml
[switch.picker]
pager = "delta --paging=never --width=$COLUMNS"
```
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 4a6a4cdeb..160968f61 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -147,6 +147,7 @@ See [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars)
Reference Taskfile/Justfile/Makefile in hooks:
```toml
+# .config/wt.toml
[pre-start]
"setup" = "task install"
@@ -159,6 +160,7 @@ Reference Taskfile/Justfile/Makefile in hooks:
Split checks across hook types — quick feedback before each commit, expensive suites before merge:
```toml
+# .config/wt.toml
[[pre-commit]]
lint = "npm run lint"
typecheck = "npm run typecheck"
@@ -175,6 +177,7 @@ build = "npm run build"
Branch on `{{ target }}` to vary behavior per merge destination — for example, deploying to production from `main` and staging from a release branch:
```toml
+# .config/wt.toml
post-merge = """
if [ {{ target }} = main ]; then
npm run deploy:production
@@ -223,6 +226,7 @@ $ wt list
Each worktree can have its own isolated database. A pipeline sets up names and ports as [vars](https://worktrunk.dev/config/#wt-config-state-vars), then later steps and hooks reference them:
```toml
+# .config/wt.toml
[[post-start]]
set-vars = """
wt config state vars set \
@@ -262,6 +266,7 @@ To scope environment variables to a worktree — a tool's package path, a profil
**direnv** — commit `.envrc` at the repo root:
```sh
+# .envrc
export MY_PACKAGES_PATH="$PWD/.packages"
```
@@ -270,6 +275,7 @@ Run `direnv allow` once per worktree to trust the file ([getting started](https:
**mise** — commit `mise.toml` at the repo root:
```toml
+# mise.toml
[env]
MY_PACKAGES_PATH = "{{ config_root }}/.packages"
```
@@ -283,6 +289,7 @@ Both set real environment variables in the shell session, so every child process
Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
@@ -290,6 +297,7 @@ copy = "wt step copy-ignored"
When another hook depends on the copy — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages — sequence them with a `[[post-start]]` pipeline:
```toml
+# .config/wt.toml
[[post-start]]
copy = "wt step copy-ignored"
@@ -452,7 +460,7 @@ This lets one agent session hand off work to another that runs in the background
The [worktrunk skill](https://worktrunk.dev/claude-code/) includes guidance for Claude Code (and other agent CLIs that load it) to execute this pattern. To enable it, request it explicitly ("spawn a parallel worktree for...") or add to your project instructions (`CLAUDE.md` or `AGENTS.md`):
-```markdown
+```markdown title="CLAUDE.md"
When I ask you to spawn parallel worktrees, use the agent handoff pattern
from the worktrunk skill.
```
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index 82527b3ec..7ca50ad7e 100644
--- a/skills/worktrunk/reference/troubleshooting.md
+++ b/skills/worktrunk/reference/troubleshooting.md
@@ -81,7 +81,7 @@ post-start = "npm run build"
### A `for-each` or `--execute` alias uses the same value in every worktree
-The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See `reference/extending.md#deferring-expansion-to-a-nested-wt-command` for how to confirm it and how to defer the variable.
+The alias body rendered once at dispatch, baking the variable to the invoking worktree's value before the nested `wt` command iterated. See `reference/extending.md#nesting-templates` for how to pass the template through unrendered.
## List
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 8b194decc..864a7e183 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -1248,6 +1248,7 @@ $ wt config state vars set env=production --branch=main
Variables are available in [hook templates](/hook/#template-variables) as `{{ vars.<key> }}`. Use the `default` filter for keys that may not be set:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.port | default('3000') }}"
```
@@ -1258,6 +1259,7 @@ JSON object and array values support dot access:
$ wt config state vars set config='{"port": 3000, "debug": true}'
```
```toml
+# .config/wt.toml
[post-start]
dev = "npm start -- --port {{ vars.config.port }}"
```
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 94984f03c..b1e26569b 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -728,6 +728,7 @@ The comparison base is the merge-base with the default branch, or with its upstr
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
```toml
+# ~/.config/worktrunk/config.toml
[switch.picker]
pager = "delta --paging=never --width=$COLUMNS"
```
@@ -898,6 +899,7 @@ Reuses the [`commit.generation`](/config/#commit) command — the same LLM that
Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — `{{ vars.* }}`, stored with [`wt config state vars set`](/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) — useful for tracking what each of many (often agent-driven) branches is for:
```toml
+# ~/.config/worktrunk/config.toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"
```
@@ -1490,6 +1492,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
+# .config/wt.toml
[[pre-merge]]
test = "cargo test"
lint = "cargo clippy"
@@ -1653,12 +1656,14 @@ Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
```toml
+# .config/wt.toml
pre-start = "npm install"
```
A table is multiple commands that run concurrently:
```toml
+# .config/wt.toml
[post-start]
server = "npm run dev"
watch = "npm run watch"
@@ -1667,6 +1672,7 @@ watch = "npm run watch"
A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
+# .config/wt.toml
[[post-start]]
install = "npm ci"
@@ -1748,6 +1754,7 @@ All hooks share the same perspective — `{{ branch | hash_port }}` produces the
Undefined variables error — use conditionals or defaults for optional behavior:
```toml
+# .config/wt.toml
[pre-start]
# Rebase onto upstream if tracking a remote branch (e.g., wt switch --create feature --base origin/feature)
sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
@@ -1760,6 +1767,7 @@ Run any hook-firing command with `-v` to see the resolved variables for the actu
Variables use dot access and the `default` filter for missing keys. JSON object/array values are parsed automatically, so `{{ vars.config.port }}` works when the value is `{"port": 3000}`:
```toml
+# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.config.port | default('3000') }}"
```
@@ -1784,6 +1792,7 @@ The `sanitize_db` filter produces database-safe identifiers — lowercase alphan
The `hash` filter is the bare 3-character base36 digest, useful for composing your own truncate-with-collision-avoidance recipes when an output budget is tight (e.g., Unix socket paths capped at 107 bytes):
```toml
+# ~/.config/worktrunk/config.toml
# Truncated branch slug + hash: collisions remain disambiguated even when prefixes match
worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"
```
@@ -1791,6 +1800,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash
The `dirname` and `basename` filters traverse paths. They're useful for bare repos in a hidden directory like `myproject/.git`, where `{{ repo }}` resolves to `.git`:
```toml
+# ~/.config/worktrunk/config.toml
# Place worktrees as siblings of the bare repo, named `<wrapper>.<branch>`
worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ branch | sanitize }}"
```
@@ -1798,6 +1808,7 @@ worktree-path = "{{ repo_path }}/../{{ repo_path | dirname | basename }}.{{ bran
The `hash_port` filter is useful for running dev servers on unique ports per worktree:
```toml
+# .config/wt.toml
[post-start]
dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port }}"
```
@@ -1805,7 +1816,9 @@ dev = "npm run dev -- --host {{ branch }}.localhost --port {{ branch | hash_port
Hash any string, including concatenations:
```toml
+# .config/wt.toml
# Unique port per repo+branch combination
+[post-start]
dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
```
@@ -1822,6 +1835,7 @@ Templates also support functions for dynamic lookups:
The `worktree_path_of_branch` function returns the filesystem path of a worktree given a branch name, or an empty string if no worktree exists for that branch. This is useful for referencing files in other worktrees:
```toml
+# .config/wt.toml
[pre-start]
# Copy config from main worktree
setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
@@ -1832,11 +1846,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path
Hooks receive all template variables as JSON on stdin, enabling complex logic that templates can't express. Variables that are unset in a template are absent from the JSON too, so read the optional ones with a default — `branch` has none in a detached worktree:
```toml
+# .config/wt.toml
[pre-start]
setup = "python3 scripts/pre-start-setup.py"
```
```python
+# scripts/pre-start-setup.py
import json, sys, subprocess
ctx = json.load(sys.stdin)
if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
@@ -1848,6 +1864,7 @@ if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']:
Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
```toml
+# .config/wt.toml
[post-start]
copy = "wt step copy-ignored"
```
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 1e43365f4..590830203 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -104,6 +104,7 @@ $ wt step commit --stage=tracked
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -150,6 +151,7 @@ $ wt step squash --stage=none
Configure the default in user config:
```toml
+# ~/.config/worktrunk/config.toml
[commit]
stage = "tracked"
```
@@ -340,6 +342,7 @@ target/
After `.worktreeinclude` selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:
```toml
+# ~/.config/worktrunk/config.toml
[step.copy-ignored]
exclude = [".cache/", ".turbo/"]
```
@@ -387,6 +390,7 @@ The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first
`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
```toml
+# .config/wt.toml
[pre-start]
deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
```
@@ -528,7 +532,7 @@ Variables substitute into each argv element before exec. See [`wt hook` template
$ wt step for-each -- echo 'Branch: {{ branch }}'
```
-Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [deferring expansion in an alias](/extending/#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.
+Each element is expanded fresh in every worktree, so `{{ branch }}` is that worktree's branch. An alias wrapping for-each renders templates earlier, in the invoking worktree; [nesting templates](/extending/#nesting-templates) shows how to keep a variable per-worktree.
## Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 4a3a58621..ef7ad117a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -204,6 +204,7 @@ Reuses the commit.generation command — the same LLM that generates com
Each [list.custom-columns] entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — {{ vars.* }}, stored with wt config state vars set, and {{ git.branch.* }}, the branch's own git config under branch.<name>.* (a jira key you set yourself, or the git-native description) — useful for tracking what each of many (often agent-driven) branches is for:
+  # ~/.config/worktrunk/config.toml
  [list.custom-columns.Ticket]
  template = "{{ vars.ticket }}"
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 43c48de20..a6eb7d0b7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -243,6 +243,7 @@ namespaces — {{ vars.* }}, stored with wt config state vars set[0
you set yourself, or the git-native description) — useful for tracking what each
of many (often agent-driven) branches is for:
+  # ~/.config/worktrunk/config.toml
  [list.custom-columns.Ticket]
  template = "{{ vars.ticket }}"
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
index f6e4337f6..f3f667b21 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -194,6 +194,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
+# .config/wt.toml
[[pre-merge]]
test = "cargo test"
lint = "cargo clippy"
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 520eb0062..0932b2b0c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -177,6 +177,7 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run wt merge, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
+  # .config/wt.toml
  [[pre-merge]]
  test = "cargo test"
  lint = "cargo clippy"
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
index 6fdc90db7..03b9a1173 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
@@ -127,6 +127,7 @@ To limit what gets copied further, create .worktreeinclude with gitignor
After .worktreeinclude selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:
+  # ~/.config/worktrunk/config.toml
  [step.copy-ignored]
  exclude = [".cache/", ".turbo/"]
@@ -170,6 +171,7 @@ The target/ directory is huge (often 1-10GB). Copying with reflink cuts
node_modules/ is large but mostly static. If the project has no native dependencies, symlinks are even faster:
+  # .config/wt.toml
  [pre-start]
  deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index a92390cf9..53ac2c9cd 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -233,6 +233,7 @@ The comparison base is the merge-base with the default branch, or with its upstr
Pager configuration: The preview panel pipes diff output through git's pager. Override in user config:
+  # ~/.config/worktrunk/config.toml
  [switch.picker]
  pager = "delta --paging=never --width=$COLUMNS"