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.jsonindex 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.mdindex 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 CodAdd 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.mdindex 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=mainVariables 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.mdindex 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.mdindex 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.mdindex 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.tomlpre-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 theUndefined 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 actuVariables 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 alphanThe `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 matchworktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"```@@ -213,6 +219,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hashThe `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 }}.{{ branThe `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_portHash 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 worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"@@ -254,11 +265,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_pathHooks 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.pyimport json, sys, subprocessctx = 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.mdindex 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 thatEach `[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.mdindex 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 syOverride 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.mdindex 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 locallyThe 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.mdindex 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=trackedConfigure the default in user config:```toml+# ~/.config/worktrunk/config.toml[commit]stage = "tracked"```@@ -219,6 +220,7 @@ $ wt step squash --stage=noneConfigure 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.### Examplesdiff --git a/docs/src/content/docs/switch.md b/docs/src/content/docs/switch.mdindex 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.mdindex 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.tomlpost-merge = """if [ {{ target }} = main ]; thennpm run deploy:production@@ -231,6 +234,7 @@ $ wt listEach 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+# .envrcexport 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 processUse [`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 backgroundThe [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 patternfrom the worktrunk skill.```diff --git a/plugins/worktrunk/skills/worktrunk/SKILL.md b/plugins/worktrunk/skills/worktrunk/SKILL.mdindex 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 commandsdiff --git a/plugins/worktrunk/skills/worktrunk/reference/claude-code.md b/plugins/worktrunk/skills/worktrunk/reference/claude-code.mdindex 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.mdindex 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=mainVariables 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.mdindex 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](hTen 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.mdindex 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.mdindex 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.tomlpre-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 theUndefined 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 actuVariables 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 alphanThe `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 matchworktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"```@@ -207,6 +213,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hashThe `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 }}.{{ branThe `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_portHash 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 worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"@@ -248,11 +259,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_pathHooks 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.pyimport json, sys, subprocessctx = 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.mdindex 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) commandEach `[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.mdindex 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 syOverride 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.mdindex 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 locallyThe 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.mdindex 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=trackedConfigure the default in user config:```toml+# ~/.config/worktrunk/config.toml[commit]stage = "tracked"```@@ -207,6 +208,7 @@ $ wt step squash --stage=noneConfigure 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.### Examplesdiff --git a/plugins/worktrunk/skills/worktrunk/reference/switch.md b/plugins/worktrunk/skills/worktrunk/reference/switch.mdindex 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.mdindex 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.tomlpost-merge = """if [ {{ target }} = main ]; thennpm run deploy:production@@ -223,6 +226,7 @@ $ wt listEach 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+# .envrcexport 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 processUse [`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 backgroundThe [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 patternfrom the worktrunk skill.```diff --git a/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.md b/plugins/worktrunk/skills/worktrunk/reference/troubleshooting.mdindex 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.## Listdiff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.mdindex 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 commandsdiff --git a/skills/worktrunk/reference/claude-code.md b/skills/worktrunk/reference/claude-code.mdindex 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.mdindex 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=mainVariables 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.mdindex 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](hTen 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.mdindex 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.mdindex 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.tomlpre-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 theUndefined 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 actuVariables 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 alphanThe `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 matchworktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"```@@ -207,6 +213,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hashThe `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 }}.{{ branThe `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_portHash 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 worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"@@ -248,11 +259,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_pathHooks 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.pyimport json, sys, subprocessctx = 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.mdindex 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) commandEach `[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.mdindex 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 syOverride 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.mdindex 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 locallyThe 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.mdindex b8770dabb..fb359164c 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -126,6 +126,7 @@ $ wt step commit --stage=trackedConfigure the default in user config:```toml+# ~/.config/worktrunk/config.toml[commit]stage = "tracked"```@@ -207,6 +208,7 @@ $ wt step squash --stage=noneConfigure 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.### Examplesdiff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 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.mdindex 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.tomlpost-merge = """if [ {{ target }} = main ]; thennpm run deploy:production@@ -223,6 +226,7 @@ $ wt listEach 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+# .envrcexport 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 processUse [`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 backgroundThe [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 patternfrom the worktrunk skill.```diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.mdindex 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.## Listdiff --git a/src/cli/config.rs b/src/cli/config.rsindex 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=mainVariables 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.rsindex 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 thatEach `[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 locallyThe 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.tomlpre-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 theUndefined 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 actuVariables 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 alphanThe `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 matchworktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hash }}"```@@ -1791,6 +1800,7 @@ worktree-path = "/tmp/{{ (branch | sanitize)[:20] }}_{{ branch | sanitize | hashThe `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 }}.{{ branThe `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_portHash 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 worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"@@ -1832,11 +1846,13 @@ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_pathHooks 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.pyimport json, sys, subprocessctx = 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.rsindex 1e43365f4..590830203 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -104,6 +104,7 @@ $ wt step commit --stage=trackedConfigure the default in user config:```toml+# ~/.config/worktrunk/config.toml[commit]stage = "tracked"```@@ -150,6 +151,7 @@ $ wt step squash --stage=noneConfigure 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.## Examplesdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex 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 [2mcommit.generation[0m command — the same LLM that generates comEach [2m[list.custom-columns][0m 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 — [2m{{ vars.* }}[0m, stored with [2mwt config state vars set[0m, and [2m{{ git.branch.* }}[0m, the branch's own git config under [2mbranch.<name>.*[0m (a [2mjira[0m key you set yourself, or the git-native [2mdescription[0m) — useful for tracking what each of many (often agent-driven) branches is for:+[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[list.custom-columns.Ticket][0m[107m [0m [2mtemplate = [0m[2m[32m"{{ vars.ticket }}"[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snapindex 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 — [2m{{ vars.* }}[0m, stored with [2mwt config state vars set[0you set yourself, or the git-native [2mdescription[0m) — useful for tracking what eachof many (often agent-driven) branches is for:+[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[list.custom-columns.Ticket][0m[107m [0m [2mtemplate = [0m[2m[32m"{{ vars.ticket }}"[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex 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 locallyThe 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.snapindex 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 locallyThe full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run [2mwt merge[0m, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.+[107m [0m [2m# .config/wt.toml[0m[107m [0m [2m[36m[[pre-merge]][0m[107m [0m [2mtest = [0m[2m[32m"cargo test"[0m[107m [0m [2mlint = [0m[2m[32m"cargo clippy"[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snapindex 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 [2m.worktreeinclude[0m with gitignorAfter [2m.worktreeinclude[0m selects entries, you can add more gitignore-style excludes in user config, per-project user overrides, or project config:+[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[step.copy-ignored][0m[107m [0m [2mexclude = [[0m[2m[32m".cache/"[0m[2m, [0m[2m[32m".turbo/"[0m[2m][0m@@ -170,6 +171,7 @@ The [2mtarget/[0m directory is huge (often 1-10GB). Copying with reflink cuts[2mnode_modules/[0m is large but mostly static. If the project has no native dependencies, symlinks are even faster:+[107m [0m [2m# .config/wt.toml[0m[107m [0m [2m[36m[pre-start][0m[107m [0m [2mdeps = [0m[2m[32m"ln -sf {{ primary_worktree_path }}/node_modules ."[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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[1mPager configuration:[0m The preview panel pipes diff output through git's pager. Override in user config:+[107m [0m [2m# ~/.config/worktrunk/config.toml[0m[107m [0m [2m[36m[switch.picker][0m[107m [0m [2mpager = [0m[2m[32m"delta --paging=never --width=$COLUMNS"[0m