Skip to content

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.toml
index 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.md
index 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.md
index 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 0
g=$(git rev-parse --git-dir)
test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
+ git update-index --refresh -q >/dev/null || true
git 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 worktree
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 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 errors
Errors 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.md
index 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.md
index 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 values
diff --git a/docs/content/step.md b/docs/content/step.md
index 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.
+
### Examples
Pull 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>&lt;ARGS&gt;...</span>
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 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 browse
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
4. **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.md
index 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 hooks
Reference 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 worktree
diff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.json
index 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.md
index 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 configuration
wt 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.md
index 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.md
index 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 0
g=$(git rev-parse --git-dir)
test -d "$g/rebase-merge" -o -d "$g/rebase-apply" && exit 0
+ git update-index --refresh -q >/dev/null || true
git 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 worktree
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 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 errors
Errors 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.md
index 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.md
index 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 values
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 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.
+
### Examples
Pull 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.md
index 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 browse
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
4. **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.md
index 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.d
git 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 hooks
Reference 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 worktree
diff --git a/skills/worktrunk/reference/troubleshooting.md b/skills/worktrunk/reference/troubleshooting.md
index 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 types
4. 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 errors
2. 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 120s
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 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.rs
index 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 browse
2. **log** — Recent commits; commits already on the default branch have dimmed hashes
3. **main…±** — Diff of changes since the merge-base with the default branch
4. **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.rs
index 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.
+
## Examples
Pull updates in worktrees with upstreams (skips others):
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 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.snap
index 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 ~/.config/worktrunk/config.toml with the following content:
  # - `{{ 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/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 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.
- {{ 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.
+
Examples for repo at ~/code/myproject, branch feature/auth:
Default — sibling directory (~/code/myproject.feature-auth):
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.snap
index 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 main or master:
  git rebase $(wt config state default-branch)
+In a hook or alias template, prefer the {{ default_branch }} template variable; $(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
@@ -87,4 +89,6 @@ 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.
+
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 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.
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
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 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: C
LC_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.
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
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 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, wt switch opens an interactive picker to
2. log — Recent commits; commits already on the default branch have dimmed hashes
3. main…± — Diff of changes since the merge-base with the default branch
4. 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
Pager configuration: The preview panel pipes diff output through git's pager. Override in user config: