Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: alias template-expansion timing; fix narrow help-test env redaction (#3006)
Maximilian Roos5da0d2c3e472
diff --git a/dev/config.example.toml b/dev/config.example.tomlindex e8de9c214..56f908a8f 100644--- a/dev/config.example.toml+++ b/dev/config.example.toml@@ -21,6 +21,8 @@# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)# - `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)#+# This is a smaller set than the variables hooks and aliases get (https://worktrunk.dev/hook/#template-variables).+## **Examples** for repo at `~/code/myproject`, branch `feature/auth`:## Default — sibling directory (`~/code/myproject.feature-auth`):diff --git a/docs/content/config.md b/docs/content/config.mdindex 7d613f987..b55ca7e48 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -83,6 +83,8 @@ Controls where new worktrees are created.- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)- `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)+This is a smaller set than [the variables hooks and aliases get](@/hook.md#template-variables).+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:Default — sibling directory (`~/code/myproject.feature-auth`):@@ -832,6 +834,8 @@ Useful in scripts to avoid hardcoding `main` or `master`:{{ terminal(cmd="git rebase $(wt config state default-branch)") }}+In a hook or alias template, prefer the `{{ default_branch }}` [template variable](@/hook.md#template-variables); `$(wt config state default-branch)` is for plain shell scripts.+Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.### Detection@@ -851,6 +855,8 @@ The local inference fallback uses these heuristics in order:- Checks `git config init.defaultBranch`- Looks for common names: `main`, `master`, `develop`, `trunk`+If none of these match, detection fails; set it explicitly with `wt config state default-branch set BRANCH`.+### Command reference{% terminal() %}diff --git a/docs/content/extending.md b/docs/content/extending.mdindex c66d1a081..77349b766 100644--- a/docs/content/extending.md+++ b/docs/content/extending.md@@ -119,14 +119,25 @@ Every step sees the same `{{ args }}` and bound variables. `wt release -- --dry-### Deferring expansion to a nested `wt` command-Alias templates render once at dispatch, using the alias-invocation worktree's context. A nested `wt` command in the alias body (for example `wt switch --execute '…'`) therefore receives already-rendered text, so a variable like `{{ worktree_path }}` inside the inner command's template resolves to the *outer* worktree rather than the one `wt switch` is targeting. Wrap the inner template in `{% raw %}…{% endraw %}` so it passes through unrendered and the inner `wt` command expands it in its own context:+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.)++`{% 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, without the extra wrapper: its `--execute '…'` argument is already a single quoted string, so only `{% raw %}` is needed. Here `{{ worktree_path }}` expands against the worktree being created, not the one the alias ran from:```toml[aliases]echo-target = "wt switch {{ args }} --no-cd --execute 'echo {% raw %}{{ worktree_path }}{% endraw %}'"```-`wt echo-target other` now prints the path of the `other` worktree, not the worktree the alias was invoked from.+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.### Recipe: rebase every worktree onto its upstream@@ -134,14 +145,15 @@ echo-target = "wt switch {{ args }} --no-cd --execute 'echo {% raw %}{{ worktree[aliases]up = '''git fetch --all --prune && wt step for-each -- sh -c '- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0+ git rev-parse --verify -q @{u} >/dev/null || exit 0g=$(git rev-parse --git-dir)test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0+ git update-index --refresh -q >/dev/null || truegit rebase @{u} --no-autostash || git rebase --abort''''```-`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.+`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, refresh the index to drop stale stat entries, then rebase and auto-abort 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.### Recipe: move or copy in-progress changes to a new worktreediff --git a/docs/content/faq.md b/docs/content/faq.mdindex 6afb75477..eda9de2f3 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -262,6 +262,14 @@ If the remote's default branch has changed (e.g., renamed from master to main),For full details on the detection mechanism, see `wt config state default-branch --help`.+## My `for-each` or `--execute` alias prints the same value in every worktree++An alias body renders once at dispatch, in the invoking worktree's context, so a per-worktree variable like `{{ branch }}` is baked to that one worktree's value before the nested `wt` command iterates. Every worktree then sees the same value.++Confirm it with `wt config alias dry-run <name>`: if the value is already substituted (e.g. `… echo branch=main`), it was baked at dispatch.++To defer a variable to the nested command, wrap it as `{% raw %}{{ branch }}{% endraw %}`; for `wt step for-each`, also keep it inside a quoted `sh -c '…'` so the alias's shell doesn't word-split it. See [deferring expansion in an alias](@/extending.md#deferring-expansion-to-a-nested-wt-command). A repo-level variable like `{{ default_branch }}` is unaffected — it is identical in every worktree.+## Installation fails with C compilation errorsErrors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 54fbeb3f0..6f2619ab5 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -148,6 +148,8 @@ Hooks can use template variables that expand at runtime:| | `{{ args }}` | Tokens forwarded from the CLI — see [Running Hooks Manually](#running-hooks-manually) || user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |+The `repo` variables (`repo`, `repo_path`, `owner`, `primary_worktree_path`, `default_branch`, `remote`, `remote_url`) are constant across the whole repository — `default_branch` is the same in every worktree. The `active` variables (`branch`, `worktree_path`, `worktree_name`, `commit`, `short_commit`, `upstream`) vary per worktree.+Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:| Operation | Bare vars | `base` | `target` |diff --git a/docs/content/list.md b/docs/content/list.mdindex dcaf35376..457149de6 100644--- a/docs/content/list.md+++ b/docs/content/list.md@@ -248,7 +248,7 @@ These values describe the relation to the default branch.### integration_reason values-When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_changes"` `"merge_adds_nothing"` `"patch-id-match"`+When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`### ci.status valuesdiff --git a/docs/content/step.md b/docs/content/step.mdindex 6aae192b2..b27090284 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -584,9 +584,9 @@ Usage: <b><span class=c>wt step eval</span></b> <span class=c>[OPTIONS]</span> <<span class="badge-experimental"></span>-Run command in each worktree. Executes sequentially with real-time output; continues on failure.+Run command in each worktree. Executes sequentially with real-time output; continues past command failures.-A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.+A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.### Arguments@@ -604,6 +604,8 @@ Variables substitute into each argv element before exec. See [`wt hook` template{{ terminal(cmd="wt step for-each -- echo 'Branch: __WT_OPEN__ branch __WT_CLOSE__'") }}+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.md#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.+### ExamplesPull updates in worktrees with upstreams (skips others):@@ -617,7 +619,7 @@ Note: This command is experimental and may change in future versions.{% terminal() %}wt step for-each - [experimental] Run command in each worktree-Executes sequentially with real-time output; continues on failure.+Executes sequentially with real-time output; continues past command failures.Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</span> <b><span class=c>--</span></b> <span class=c><ARGS>...</span>diff --git a/docs/content/switch.md b/docs/content/switch.mdindex 8c0a85cf2..3d953a3c5 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -85,7 +85,7 @@ When called without arguments, `wt switch` opens an interactive picker to browse2. **log** — Recent commits; commits already on the default branch have dimmed hashes3. **main…±** — Diff of changes since the merge-base with the default branch4. **remote⇅** — Ahead/behind diff vs upstream tracking branch-5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and [`commit.generation`](@/config.md#commit)**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 614d02403..bfc1aeddc 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -105,7 +105,7 @@ docker run -d --rm \db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `pre-remove` reads the same vars to stop the container.The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).@@ -206,6 +206,8 @@ Worktrunk maintains useful state. Default branch [detection](@/config.md#wt-conf{{ terminal(cmd="git rebase $(wt config state default-branch)") }}+In hooks and aliases, the same value is the `{{ default_branch }}` [template variable](@/hook.md#template-variables); reserve this command for plain shell scripts.+## Task runners in hooksReference Taskfile/Justfile/Makefile in hooks:@@ -232,7 +234,7 @@ test = "npm test"build = "npm run build"```-`pre-commit` runs on every squash commit during `wt merge`; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.+`pre-commit` runs during `wt merge`, before the squash commit; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.## Target-specific hooks@@ -314,7 +316,7 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"To create a worktree and immediately attach:{% terminal() %}-<span class="cmd">wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'</span>+<span class="cmd">wt switch --create feature -x tmux -- attach -t '{{ branch | sanitize }}'</span>{% end %}## cmux workspace per worktreediff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.jsonindex 1c8805189..f61a6d761 100644--- a/docs/static/.well-known/agent-skills/index.json+++ b/docs/static/.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 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:1723b48a5a3a8a0a1b314dfadc96eed03aa5382ce7b572b62fd8a6248a543e82"+ "digest": "sha256:b98a9406490be008d879cfa4452a373cefafc531e9df11ef1e92c8a5a04fa670"}]}diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.mdindex 78a37ee7d..a4ea2e9ac 100644--- a/skills/worktrunk/SKILL.md+++ b/skills/worktrunk/SKILL.md@@ -16,8 +16,9 @@ Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documenta- **reference/config.md**: User and project configuration (LLM, hooks, command defaults)- **reference/hook.md**: Hook types, timing, and execution order- **reference/switch.md**, **merge.md**, **list.md**, etc.: Command documentation+- **reference/extending.md**: Aliases, multi-step pipelines, custom subcommands, and template-expansion gotchas (two-pass `{% raw %}` deferral, for-each recipes)- **reference/llm-commits.md**: LLM commit message generation-- **reference/tips-patterns.md**: Language-specific tips and patterns+- **reference/tips-patterns.md**: Practical recipes — aliases, per-branch variables, dev server per worktree, parallel agent patterns- **reference/shell-integration.md**: Shell integration debugging- **reference/troubleshooting.md**: Troubleshooting for LLM and hooks (Claude-specific)@@ -104,13 +105,16 @@ Common request for workflow automation. Follow discovery process:- For Rust: Common cargo commands- For Python: Check pyproject.toml-3. **Design appropriate hooks** (7 hook types available)+3. **Design appropriate hooks** (10 hook types: 5 events × pre/post — see `reference/hook.md`)- Dependencies (fast, must complete) → `pre-start`- Tests/linting (must pass) → `pre-commit` or `pre-merge`- Long builds, dev servers → `post-start`+ - Setup before branch resolution → `pre-switch`- Terminal/IDE updates → `post-switch`+ - After-commit triggers (CI, notifications) → `post-commit`- Deployment → `post-merge`- - Cleanup tasks → `pre-remove`+ - Cleanup before removal → `pre-remove`+ - Cleanup after removal (stop servers, remove containers) → `post-remove`4. **Validate commands work**```bash@@ -147,14 +151,15 @@ When users want to add automation to an existing project:1. **Read existing config**: `cat .config/wt.toml`-2. **Determine hook type** - When should this run?+2. **Determine hook type** - When should this run? (10 types: 5 events × pre/post)- Creating worktree (blocking) → `pre-start`- Creating worktree (background) → `post-start`- - Every switch → `post-switch`+ - Before/after a switch → `pre-switch` / `post-switch`- Before committing → `pre-commit`+ - After committing (CI, notifications) → `post-commit`- Before merging → `pre-merge`- After merging → `post-merge`- - Before removal → `pre-remove`+ - Before/after removal → `pre-remove` / `post-remove`3. **Handle format conversion if needed**@@ -211,26 +216,32 @@ bash -n -c "if [ true ]; then echo ok; fi"### User Config Tasks- Set up commit message generation → `reference/llm-commits.md`- Customize worktree paths → `reference/config.md#worktree-path-template`-- Custom commit templates → `reference/llm-commits.md#templates`-- Configure command defaults → `reference/config.md#command-settings`-- Set up personal hooks → `reference/config.md#user-hooks`+- Custom commit templates → `reference/llm-commits.md#prompt-templates`+- Configure command defaults → `reference/config.md#command-config`+- Set up personal hooks → `reference/config.md#hooks`### Project Config Tasks- Set up hooks for new project → `reference/hook.md`-- Add hook to existing config → `reference/hook.md#configuration`+- Add hook to existing config → `reference/hook.md#hook-forms`- Use template variables → `reference/hook.md#template-variables`- Add dev server URL to list → `reference/config.md#dev-server-url`+### Aliases & Multi-Worktree Tasks+- 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`+## Key Commands```bash# View all configurationwt config show-# Create initial user config+# Create initial user config (LLM/commit setup: see reference/llm-commits.md)wt config create-# LLM setup guide+# Full config reference (subcommands, templates, env vars)wt config --help```diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 48163bff4..a356f3036 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -82,6 +82,8 @@ Controls where new worktrees are created.- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)- `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)+This is a smaller set than [the variables hooks and aliases get](https://worktrunk.dev/hook/#template-variables).+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:Default — sibling directory (`~/code/myproject.feature-auth`):@@ -862,6 +864,8 @@ Useful in scripts to avoid hardcoding `main` or `master`:$ git rebase $(wt config state default-branch)```+In a hook or alias template, prefer the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.+Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.### Detection@@ -881,6 +885,8 @@ The local inference fallback uses these heuristics in order:- Checks `git config init.defaultBranch`- Looks for common names: `main`, `master`, `develop`, `trunk`+If none of these match, detection fails; set it explicitly with `wt config state default-branch set BRANCH`.+### Command reference```diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 58dbc71bf..101ac86e7 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -123,14 +123,25 @@ Every step sees the same `{{ args }}` and bound variables. `wt release -- --dry-### Deferring expansion to a nested `wt` command-Alias templates render once at dispatch, using the alias-invocation worktree's context. A nested `wt` command in the alias body (for example `wt switch --execute '…'`) therefore receives already-rendered text, so a variable like `{{ worktree_path }}` inside the inner command's template resolves to the *outer* worktree rather than the one `wt switch` is targeting. Wrap the inner template in `{% raw %}…{% endraw %}` so it passes through unrendered and the inner `wt` command expands it in its own context:+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.)++`{% 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, without the extra wrapper: its `--execute '…'` argument is already a single quoted string, so only `{% raw %}` is needed. Here `{{ worktree_path }}` expands against the worktree being created, not the one the alias ran from:```toml[aliases]echo-target = "wt switch {{ args }} --no-cd --execute 'echo {% raw %}{{ worktree_path }}{% endraw %}'"```-`wt echo-target other` now prints the path of the `other` worktree, not the worktree the alias was invoked from.+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.### Recipe: rebase every worktree onto its upstream@@ -138,14 +149,15 @@ echo-target = "wt switch {{ args }} --no-cd --execute 'echo {% raw %}{{ worktree[aliases]up = '''git fetch --all --prune && wt step for-each -- sh -c '- git rev-parse --verify @{u} >/dev/null 2>&1 || exit 0+ git rev-parse --verify -q @{u} >/dev/null || exit 0g=$(git rev-parse --git-dir)test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0+ git update-index --refresh -q >/dev/null || truegit rebase @{u} --no-autostash || git rebase --abort''''```-`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, otherwise rebase and auto-abort on conflict.+`wt up` fetches all remotes, then iterates every worktree: skip if no upstream, skip if mid-rebase, refresh the index to drop stale stat entries, then rebase and auto-abort 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.### Recipe: move or copy in-progress changes to a new worktreediff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex ee97f3c5f..75cd0db00 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -255,6 +255,14 @@ If the remote's default branch has changed (e.g., renamed from master to main),For full details on the detection mechanism, see `wt config state default-branch --help`.+## My `for-each` or `--execute` alias prints the same value in every worktree++An alias body renders once at dispatch, in the invoking worktree's context, so a per-worktree variable like `{{ branch }}` is baked to that one worktree's value before the nested `wt` command iterates. Every worktree then sees the same value.++Confirm it with `wt config alias dry-run <name>`: if the value is already substituted (e.g. `… echo branch=main`), it was baked at dispatch.++To defer a variable to the nested command, wrap it as `{% raw %}{{ branch }}{% endraw %}`; for `wt step for-each`, also keep it inside a quoted `sh -c '…'` so the alias's shell doesn't word-split it. See [deferring expansion in an alias](https://worktrunk.dev/extending/#deferring-expansion-to-a-nested-wt-command). A repo-level variable like `{{ default_branch }}` is unaffected — it is identical in every worktree.+## Installation fails with C compilation errorsErrors related to tree-sitter or C compilation (C99 mode, `le16toh` undefined) can be avoided by installing without syntax highlighting:diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 2184e3029..4248e2dbe 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -139,6 +139,8 @@ Hooks can use template variables that expand at runtime:| | `{{ args }}` | Tokens forwarded from the CLI — see [Running Hooks Manually](#running-hooks-manually) || user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars) |+The `repo` variables (`repo`, `repo_path`, `owner`, `primary_worktree_path`, `default_branch`, `remote`, `remote_url`) are constant across the whole repository — `default_branch` is the same in every worktree. The `active` variables (`branch`, `worktree_path`, `worktree_name`, `commit`, `short_commit`, `upstream`) vary per worktree.+Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:| Operation | Bare vars | `base` | `target` |diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.mdindex a2e8ef8a3..1a599965a 100644--- a/skills/worktrunk/reference/list.md+++ b/skills/worktrunk/reference/list.md@@ -259,7 +259,7 @@ These values describe the relation to the default branch.### integration_reason values-When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_changes"` `"merge_adds_nothing"` `"patch-id-match"`+When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`### ci.status valuesdiff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex 7f5e178f1..1db454609 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -601,9 +601,9 @@ Global Options:[experimental]-Run command in each worktree. Executes sequentially with real-time output; continues on failure.+Run command in each worktree. Executes sequentially with real-time output; continues past command failures.-A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.+A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.### Arguments@@ -629,6 +629,8 @@ 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.+### ExamplesPull updates in worktrees with upstreams (skips others):@@ -644,7 +646,7 @@ Note: This command is experimental and may change in future versions.```wt step for-each - [experimental] Run command in each worktree-Executes sequentially with real-time output; continues on failure.+Executes sequentially with real-time output; continues past command failures.Usage: wt step for-each [OPTIONS] -- <ARGS>...diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex e8c7bb977..fa1eac020 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -81,7 +81,7 @@ When called without arguments, `wt switch` opens an interactive picker to browse2. **log** — Recent commits; commits already on the default branch have dimmed hashes3. **main…±** — Diff of changes since the merge-base with the default branch4. **remote⇅** — Ahead/behind diff vs upstream tracking branch-5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and [`commit.generation`](https://worktrunk.dev/config/#commit)**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex b77d553e4..f9e33e459 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -98,7 +98,7 @@ docker run -d --rm \db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"```-The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `post-remove` reads the same vars to stop the container.+The first pipeline step derives values from the branch and stores them as vars. The second step references `{{ vars.container }}` and `{{ vars.port }}` — expanded at execution time, after the vars are set. `pre-remove` reads the same vars to stop the container.The `('db-' ~ branch)` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide. The `sanitize_db` filter produces database-safe identifiers (lowercase, underscores, no leading digits, with a short hash suffix).@@ -211,6 +211,8 @@ Worktrunk maintains useful state. Default branch [detection](https://worktrunk.dgit rebase $(wt config state default-branch)```+In hooks and aliases, the same value is the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); reserve this command for plain shell scripts.+## Task runners in hooksReference Taskfile/Justfile/Makefile in hooks:@@ -237,7 +239,7 @@ test = "npm test"build = "npm run build"```-`pre-commit` runs on every squash commit during `wt merge`; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.+`pre-commit` runs during `wt merge`, before the squash commit; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.## Target-specific hooks@@ -331,7 +333,7 @@ tmux = "tmux kill-session -t {{ branch | sanitize }} 2>/dev/null || true"To create a worktree and immediately attach:```bash-$ wt switch --create feature -x 'tmux attach -t {{ branch | sanitize }}'+$ wt switch --create feature -x tmux -- attach -t '{{ branch | sanitize }}'```## cmux workspace per worktreediff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.mdindex 62d8f7e7d..6b30ab3b5 100644--- a/skills/worktrunk/reference/troubleshooting.md+++ b/skills/worktrunk/reference/troubleshooting.md@@ -50,7 +50,7 @@ If a template file is used, verify it exists at the specified path.Check sequence:1. Verify `.config/wt.toml` exists: `ls -la .config/wt.toml`2. Check TOML syntax (use `wt hook show` to see parsed config)-3. Verify hook type spelling matches one of the seven types+3. Verify hook type spelling matches one of the ten types4. Test command manually in the worktree### Hook failing@@ -58,7 +58,7 @@ Check sequence:Debug steps:1. Run the command manually in the worktree to see errors2. Check for missing dependencies (npm packages, system tools)-3. Verify template variables expand correctly (`wt hook show --verbose`)+3. Verify template variables expand correctly with `wt hook show --expanded` (shows each command with its variables substituted)4. For background hooks, check `.git/wt/logs/` for output### Slow blocking hooks@@ -74,6 +74,17 @@ pre-start = "npm install"post-start = "npm run build"```+## Aliases++### Inspecting an alias++- `wt config alias show <name>` prints the raw template.+- `wt config alias dry-run <name> [-- args...]` prints the rendered command without running it.++### A `for-each` or `--execute` alias uses the same value in every worktree++The alias body renders once at dispatch, in the invoking worktree, so a per-worktree variable like `{{ branch }}` is baked before the nested `wt` command iterates. If `wt config alias dry-run <name>` shows a single substituted value (e.g. `… echo branch=main`), it was baked at that first pass. Defer it with `{% raw %}{{ branch }}{% endraw %}`, and for `for-each` keep it inside a quoted `sh -c '...'` so the alias's shell doesn't word-split it. Repo-level variables like `{{ default_branch }}` are unaffected — they are identical in every worktree. See `reference/extending.md#deferring-expansion-to-a-nested-wt-command`.+## List### `wt list` times out after 120sdiff --git a/src/cli/config.rs b/src/cli/config.rsindex fd4ec6284..88ec10c6c 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -705,6 +705,8 @@ to clear specific state."#)]$ git rebase $(wt config state default-branch)```+In a hook or alias template, prefer the `{{ default_branch }}` [template variable](@/hook.md#template-variables); `$(wt config state default-branch)` is for plain shell scripts.+Without a subcommand, runs `get`. Use `set` to override, or `clear` then `get` to re-detect.## Detection@@ -722,7 +724,9 @@ The local inference fallback uses these heuristics in order:- If only one local branch exists, uses it- For bare repos or empty repos, checks `symbolic-ref HEAD`- Checks `git config init.defaultBranch`-- Looks for common names: `main`, `master`, `develop`, `trunk`"#+- Looks for common names: `main`, `master`, `develop`, `trunk`++If none of these match, detection fails; set it explicitly with `wt config state default-branch set BRANCH`."#)]DefaultBranch {#[command(subcommand)]diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 28cd0fdb8..ae8dd8bbc 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -630,7 +630,7 @@ When called without arguments, `wt switch` opens an interactive picker to browse2. **log** — Recent commits; commits already on the default branch have dimmed hashes3. **main…±** — Diff of changes since the merge-base with the default branch4. **remote⇅** — Ahead/behind diff vs upstream tracking branch-5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and `[commit.generation]`+5. **summary** — LLM-generated branch summary; requires `[list] summary = true` and [`commit.generation`](@/config.md#commit)**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:@@ -942,7 +942,7 @@ These values describe the relation to the default branch.### integration_reason values-When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_changes"` `"merge_adds_nothing"` `"patch-id-match"`+When `main_state == "integrated"`: `"ancestor"` `"trees-match"` `"no-added-changes"` `"merge-adds-nothing"` `"patch-id-match"`### ci.status values@@ -1367,6 +1367,8 @@ Hooks can use template variables that expand at runtime:| | `{{ args }}` | Tokens forwarded from the CLI — see [Running Hooks Manually](#running-hooks-manually) || user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |+The `repo` variables (`repo`, `repo_path`, `owner`, `primary_worktree_path`, `default_branch`, `remote`, `remote_url`) are constant across the whole repository — `default_branch` is the same in every worktree. The `active` variables (`branch`, `worktree_path`, `worktree_name`, `commit`, `short_commit`, `upstream`) vary per worktree.+Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:| Operation | Bare vars | `base` | `target` |@@ -1655,6 +1657,8 @@ Controls where new worktrees are created.- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)- `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)+This is a smaller set than [the variables hooks and aliases get](@/hook.md#template-variables).+**Examples** for repo at `~/code/myproject`, branch `feature/auth`:Default — sibling directory (`~/code/myproject.feature-auth`):diff --git a/src/cli/step.rs b/src/cli/step.rsindex 504ad5eac..d937c5fdc 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -455,9 +455,9 @@ Note: This command is experimental and may change in future versions./// \[experimental\] Run command in each worktree///- /// Executes sequentially with real-time output; continues on failure.+ /// Executes sequentially with real-time output; continues past command failures.#[command(- after_long_help = r#"A summary of successes and failures is shown at the end. Context JSON is piped to stdin for scripts that need structured data.+ after_long_help = r#"A summary of successes and failures is shown at the end. A template-expansion error (a malformed `{{ … }}` argument) aborts the whole run; only command failures are tolerated and reported. Context JSON — a flat object of every template variable — is piped to stdin for scripts that need structured data.## Arguments@@ -483,6 +483,8 @@ 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.md#deferring-expansion-to-a-nested-wt-command) shows how to keep a variable per-worktree.+## ExamplesPull updates in worktrees with upstreams (skips others):diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rsindex eef5e66a0..02c05e48f 100644--- a/tests/integration_tests/help.rs+++ b/tests/integration_tests/help.rs@@ -213,6 +213,7 @@ fn test_help_md_subcommand() {fn test_help_list_narrow_terminal() {let mut settings = Settings::clone_current();settings.set_snapshot_path("../snapshots");+ add_standard_env_redactions(&mut settings);settings.bind(|| {let mut cmd = wt_command();cmd.env("COLUMNS", "80");diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex 54f6cff74..923ac7d08 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap@@ -88,6 +88,8 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m# - `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)[0m[107m [0m [2m# - `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)[0m[107m [0m [2m#[0m+[107m [0m [2m# This is a smaller set than the variables hooks and aliases get (https://worktrunk.dev/hook/#template-variables).[0m+[107m [0m [2m#[0m[107m [0m [2m# **Examples** for repo at `~/code/myproject`, branch `feature/auth`:[0m[107m [0m [2m#[0m[107m [0m [2m# Default — sibling directory (`~/code/myproject.feature-auth`):[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 6edc182b5..46cb7cbcd 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap@@ -136,6 +136,8 @@ Controls where new worktrees are created.- [2m{{ branch | sanitize_db }}[0m — database-safe: lowercase, underscores, hash suffix (e.g., [2mfeature_auth_x7k[0m)- [2m{{ branch | codename(2) }}[0m — deterministic friendly name from a ~1.26M-combo pool (e.g., [2mmalleable-opah[0m)+This is a smaller set than the variables hooks and aliases get.+[1mExamples[0m for repo at [2m~/code/myproject[0m, branch [2mfeature/auth[0m:Default — sibling directory ([2m~/code/myproject.feature-auth[0m):diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snapindex afff857c4..f05d17574 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap@@ -68,6 +68,8 @@ Useful in scripts to avoid hardcoding [2mmain[0m or [2mmaster[0m:[107m [0m [2m[0m[2m[34mgit[0m[2m rebase $([0m[2m[34mwt[0m[2m config state default-branch)[0m+In a hook or alias template, prefer the [2m{{ default_branch }}[0m template variable; [2m$(wt config state default-branch)[0m is for plain shell scripts.+Without a subcommand, runs [2mget[0m. Use [2mset[0m to override, or [2mclear[0m then [2mget[0m to re-detect.[1m[32mDetection[0m@@ -87,4 +89,6 @@ The local inference fallback uses these heuristics in order:- Checks [2mgit config init.defaultBranch[0m- Looks for common names: [2mmain[0m, [2mmaster[0m, [2mdevelop[0m, [2mtrunk[0m+If none of these match, detection fails; set it explicitly with [2mwt config state default-branch set BRANCH[0m.+----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snapindex a61d7ef92..c4659a479 100644--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap@@ -327,7 +327,7 @@ These values describe the relation to the default branch.[32mintegration_reason values[0m-When [2mmain_state == "integrated"[0m: [2m"ancestor"[0m [2m"trees_match"[0m [2m"no_added_changes"[0m [2m"merge_adds_nothing"[0m [2m"patch-id-match"[0m+When [2mmain_state == "integrated"[0m: [2m"ancestor"[0m [2m"trees-match"[0m [2m"no-added-changes"[0m [2m"merge-adds-nothing"[0m [2m"patch-id-match"[0m[32mci.status values[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 cb7c687a3..5da1693e4 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@@ -11,14 +11,14 @@ info:GIT_EDITOR: ""LANG: CLC_ALL: C- LLVM_PROFILE_FILE: /var/folders/v3/8k5q0_6j3_q6gl4h8czr66sh0000gn/T/wt-test-profraw/cov-%m_%p.profraw+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"NO_COLOR: ""PSModulePath: ""SHELL: ""TERM: alacritty- WORKTRUNK_APPROVALS_PATH: /nonexistent/wt/approvals.toml- WORKTRUNK_CONFIG_PATH: /nonexistent/wt/config.toml- WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"WORKTRUNK_TEST_BASH_INSTALLED: "0"WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"WORKTRUNK_TEST_CODEX_INSTALLED: "0"@@ -380,8 +380,8 @@ These values describe the relation to the default branch.[32mintegration_reason values[0m-When [2mmain_state == "integrated"[0m: [2m"ancestor"[0m [2m"trees_match"[0m [2m"no_added_changes"[0m-[2m"merge_adds_nothing"[0m [2m"patch-id-match"[0m+When [2mmain_state == "integrated"[0m: [2m"ancestor"[0m [2m"trees-match"[0m [2m"no-added-changes"[0m+[2m"merge-adds-nothing"[0m [2m"patch-id-match"[0m[32mci.status values[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 4b3856571..5da8b3eb0 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -194,7 +194,7 @@ When called without arguments, [2mwt switch[0m opens an interactive picker to2. [1mlog[0m — Recent commits; commits already on the default branch have dimmed hashes3. [1mmain…±[0m — Diff of changes since the merge-base with the default branch4. [1mremote⇅[0m — Ahead/behind diff vs upstream tracking branch-5. [1msummary[0m — LLM-generated branch summary; requires [2m[list] summary = true[0m and [2m[commit.generation][0m+5. [1msummary[0m — LLM-generated branch summary; requires [2m[list] summary = true[0m and [2mcommit.generation[0m[1mPager configuration:[0m The preview panel pipes diff output through git's pager. Override in user config: