Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(hook): teach pipelines as [[hook]] blocks; add TOML notes to config::commands (#2149)
Maximilian Roos7e12435b33a1
diff --git a/docs/content/extending.md b/docs/content/extending.mdindex 98ab3a222..d9d9af63c 100644--- a/docs/content/extending.md+++ b/docs/content/extending.md@@ -59,11 +59,13 @@ watcher = "npm run watch"``````toml-# Pipeline: steps run in order, commands within a step run concurrently-post-start = [- "npm ci",- { server = "npm start", build = "npm run build" }-]+# Pipeline: blocks run in order, commands within a block run concurrently+[[post-start]]+install = "npm ci"++[[post-start]]+server = "npm start"+build = "npm run build"```### Template variablesdiff --git a/docs/content/hook.md b/docs/content/hook.mdindex dcbd669a8..d96a9c0f7 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -84,13 +84,15 @@ server = "npm run dev"watch = "npm run watch"```-A pipeline is a list of steps run in order, where each step is an inline table of commands that run concurrently within the step:+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:```toml-post-start = [- {install = "npm ci"},- {build = "npm run build", server = "npm run dev"},-]+[[post-start]]+install = "npm ci"++[[post-start]]+build = "npm run build"+server = "npm run dev"```Here `install` runs first, then `build` and `server` run together.@@ -248,24 +250,27 @@ build = "npm run build"lint = "npm run lint"```-When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:+When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order:```toml-# A list of two maps, run in order.-# Each map runs its entries concurrently.-post-start = [- # install runs first- { install = "npm install" },- # ...then build and lint run concurrently- { build = "npm run build", lint = "npm run lint" }-]+# Two blocks, run in order.+# Each block runs its entries concurrently.++# install runs first+[[post-start]]+install = "npm install"++# ...then build and lint run concurrently+[[post-start]]+build = "npm run build"+lint = "npm run lint"```-In summary:+In summary, the bracket count tracks the shape:-- **String** — one command-- **Map** of `name = "command"` pairs — run concurrently-- **List** of maps — run in order+- `post-start = "npm install"` — one command+- `[post-start]` — one section of concurrent commands+- `[[post-start]]` — one of multiple sections, run in order## How it works@@ -310,10 +315,11 @@ copy = "wt step copy-ignored"Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:```toml-pre-start = [- {copy = "wt step copy-ignored"},- {install = "pnpm install"},-]+[[pre-start]]+copy = "wt step copy-ignored"++[[pre-start]]+install = "pnpm install"```## Dev servers@@ -347,22 +353,23 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branEach worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-post-start = [- { set-vars = """- wt config state vars set \- container='{{ repo }}-{{ branch | sanitize }}-postgres' \- port='{{ ('db-' ~ branch) | hash_port }}' \- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'- """ },- { db = """- docker run -d --rm \- --name {{ vars.container }} \- -p {{ vars.port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16- """},-]+[[post-start]]+set-vars = """+wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+"""++[[post-start]]+db = """+docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""[post-remove]db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"@@ -379,15 +386,17 @@ The connection string is accessible anywhere — not just in hooks:Quick checks before commit, thorough validation before merge:```toml-pre-commit = [- {lint = "npm run lint"},- {typecheck = "npm run typecheck"},-]--pre-merge = [- {test = "npm test"},- {build = "npm run build"},-]+[[pre-commit]]+lint = "npm run lint"++[[pre-commit]]+typecheck = "npm run typecheck"++[[pre-merge]]+test = "npm test"++[[pre-merge]]+build = "npm run build"```## Target-specific behavior@@ -420,20 +429,23 @@ For copying dependencies and caches between worktrees, see [`wt step copy-ignore```tomlpost-merge = "cargo install --path ."-pre-start = [- {install = "npm ci"},- {env = "echo 'PORT={{ branch | hash_port }}' > .env.local"},-]+[[pre-start]]+install = "npm ci"++[[pre-start]]+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"++[[pre-commit]]+format = "cargo fmt -- --check"++[[pre-commit]]+lint = "cargo clippy -- -D warnings"-pre-commit = [- {format = "cargo fmt -- --check"},- {lint = "cargo clippy -- -D warnings"},-]+[[pre-merge]]+test = "cargo test"-pre-merge = [- {test = "cargo test"},- {build = "cargo build --release"},-]+[[pre-merge]]+build = "cargo build --release"[pre-switch]pull = """diff --git a/docs/content/merge.md b/docs/content/merge.mdindex 5cc91a945..2aff9f17c 100644--- a/docs/content/merge.md+++ b/docs/content/merge.md@@ -70,10 +70,11 @@ 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-pre-merge = [- {test = "cargo test"},- {lint = "cargo clippy"},-]+[[pre-merge]]+test = "cargo test"++[[pre-merge]]+lint = "cargo clippy"```## See alsodiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 499f5764c..c25e9f2ab 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -81,22 +81,23 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whiEach worktree can have its own isolated database. A pipeline sets up names and ports as [vars](@/config.md#wt-config-state-vars), then later steps and hooks reference them:```toml-post-start = [- """- wt config state vars set \- container='{{ repo }}-{{ branch | sanitize }}-postgres' \- port='{{ ('db-' ~ branch) | hash_port }}' \- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'- """,- { db = """- docker run -d --rm \- --name {{ vars.container }} \- -p {{ vars.port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16- """},-]+[[post-start]]+set-vars = """+wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+"""++[[post-start]]+db = """+docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""[pre-remove]db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"@@ -128,10 +129,11 @@ All gitignored files are copied by default. To limit what gets copied, create `.`pre-merge` hooks run before merging. Failures abort the merge:```toml-pre-merge = [- {"lint" = "uv run ruff check"},- {"test" = "uv run pytest"},-]+[[pre-merge]]+lint = "uv run ruff check"++[[pre-merge]]+test = "uv run pytest"```This catches issues locally before pushing — like running CI locally.diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 4733e38fa..f846b7b74 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -52,11 +52,13 @@ watcher = "npm run watch"``````toml-# Pipeline: steps run in order, commands within a step run concurrently-post-start = [- "npm ci",- { server = "npm start", build = "npm run build" }-]+# Pipeline: blocks run in order, commands within a block run concurrently+[[post-start]]+install = "npm ci"++[[post-start]]+server = "npm start"+build = "npm run build"```### Template variablesdiff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex ffd37fa1d..8e8bdd47d 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -75,13 +75,15 @@ server = "npm run dev"watch = "npm run watch"```-A pipeline is a list of steps run in order, where each step is an inline table of commands that run concurrently within the step:+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:```toml-post-start = [- {install = "npm ci"},- {build = "npm run build", server = "npm run dev"},-]+[[post-start]]+install = "npm ci"++[[post-start]]+build = "npm run build"+server = "npm run dev"```Here `install` runs first, then `build` and `server` run together.@@ -246,24 +248,27 @@ build = "npm run build"lint = "npm run lint"```-When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:+When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order:```toml-# A list of two maps, run in order.-# Each map runs its entries concurrently.-post-start = [- # install runs first- { install = "npm install" },- # ...then build and lint run concurrently- { build = "npm run build", lint = "npm run lint" }-]+# Two blocks, run in order.+# Each block runs its entries concurrently.++# install runs first+[[post-start]]+install = "npm install"++# ...then build and lint run concurrently+[[post-start]]+build = "npm run build"+lint = "npm run lint"```-In summary:+In summary, the bracket count tracks the shape:-- **String** — one command-- **Map** of `name = "command"` pairs — run concurrently-- **List** of maps — run in order+- `post-start = "npm install"` — one command+- `[post-start]` — one section of concurrent commands+- `[[post-start]]` — one of multiple sections, run in order## How it works@@ -308,10 +313,11 @@ copy = "wt step copy-ignored"Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:```toml-pre-start = [- {copy = "wt step copy-ignored"},- {install = "pnpm install"},-]+[[pre-start]]+copy = "wt step copy-ignored"++[[pre-start]]+install = "pnpm install"```## Dev servers@@ -345,22 +351,23 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branEach worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-post-start = [- { set-vars = """- wt config state vars set \- container='{{ repo }}-{{ branch | sanitize }}-postgres' \- port='{{ ('db-' ~ branch) | hash_port }}' \- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'- """ },- { db = """- docker run -d --rm \- --name {{ vars.container }} \- -p {{ vars.port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16- """},-]+[[post-start]]+set-vars = """+wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+"""++[[post-start]]+db = """+docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""[post-remove]db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"@@ -379,15 +386,17 @@ $ DATABASE_URL=$(wt config state vars get db_url) npm startQuick checks before commit, thorough validation before merge:```toml-pre-commit = [- {lint = "npm run lint"},- {typecheck = "npm run typecheck"},-]+[[pre-commit]]+lint = "npm run lint"++[[pre-commit]]+typecheck = "npm run typecheck"-pre-merge = [- {test = "npm test"},- {build = "npm run build"},-]+[[pre-merge]]+test = "npm test"++[[pre-merge]]+build = "npm run build"```## Target-specific behavior@@ -420,20 +429,23 @@ For copying dependencies and caches between worktrees, see [`wt step copy-ignore```tomlpost-merge = "cargo install --path ."-pre-start = [- {install = "npm ci"},- {env = "echo 'PORT={{ branch | hash_port }}' > .env.local"},-]+[[pre-start]]+install = "npm ci"++[[pre-start]]+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"++[[pre-commit]]+format = "cargo fmt -- --check"++[[pre-commit]]+lint = "cargo clippy -- -D warnings"-pre-commit = [- {format = "cargo fmt -- --check"},- {lint = "cargo clippy -- -D warnings"},-]+[[pre-merge]]+test = "cargo test"-pre-merge = [- {test = "cargo test"},- {build = "cargo build --release"},-]+[[pre-merge]]+build = "cargo build --release"[pre-switch]pull = """diff --git a/skills/worktrunk/reference/merge.md b/skills/worktrunk/reference/merge.mdindex 31151f12a..cd64e4def 100644--- a/skills/worktrunk/reference/merge.md+++ b/skills/worktrunk/reference/merge.md@@ -66,10 +66,11 @@ 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-pre-merge = [- {test = "cargo test"},- {lint = "cargo clippy"},-]+[[pre-merge]]+test = "cargo test"++[[pre-merge]]+lint = "cargo clippy"```## Command referencediff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex 076196179..2fda5fc98 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -74,22 +74,23 @@ Ports are deterministic — `fix-auth` always gets port 16460, regardless of whiEach 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-post-start = [- """- wt config state vars set \- container='{{ repo }}-{{ branch | sanitize }}-postgres' \- port='{{ ('db-' ~ branch) | hash_port }}' \- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'- """,- { db = """- docker run -d --rm \- --name {{ vars.container }} \- -p {{ vars.port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16- """},-]+[[post-start]]+set-vars = """+wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+"""++[[post-start]]+db = """+docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""[pre-remove]db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"@@ -123,10 +124,11 @@ All gitignored files are copied by default. To limit what gets copied, create `.`pre-merge` hooks run before merging. Failures abort the merge:```toml-pre-merge = [- {"lint" = "uv run ruff check"},- {"test" = "uv run pytest"},-]+[[pre-merge]]+lint = "uv run ruff check"++[[pre-merge]]+test = "uv run pytest"```This catches issues locally before pushing — like running CI locally.diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex a24772ce2..56d624c61 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1059,10 +1059,11 @@ 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-pre-merge = [- {test = "cargo test"},- {lint = "cargo clippy"},-]+[[pre-merge]]+test = "cargo test"++[[pre-merge]]+lint = "cargo clippy"```## See also@@ -1283,13 +1284,15 @@ server = "npm run dev"watch = "npm run watch"```-A pipeline is a list of steps run in order, where each step is an inline table of commands that run concurrently within the step:+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:```toml-post-start = [- {install = "npm ci"},- {build = "npm run build", server = "npm run dev"},-]+[[post-start]]+install = "npm ci"++[[post-start]]+build = "npm run build"+server = "npm run dev"```Here `install` runs first, then `build` and `server` run together.@@ -1454,24 +1457,27 @@ build = "npm run build"lint = "npm run lint"```-When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:+When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order:```toml-# A list of two maps, run in order.-# Each map runs its entries concurrently.-post-start = [- # install runs first- { install = "npm install" },- # ...then build and lint run concurrently- { build = "npm run build", lint = "npm run lint" }-]+# Two blocks, run in order.+# Each block runs its entries concurrently.++# install runs first+[[post-start]]+install = "npm install"++# ...then build and lint run concurrently+[[post-start]]+build = "npm run build"+lint = "npm run lint"```-In summary:+In summary, the bracket count tracks the shape:-- **String** — one command-- **Map** of `name = "command"` pairs — run concurrently-- **List** of maps — run in order+- `post-start = "npm install"` — one command+- `[post-start]` — one section of concurrent commands+- `[[post-start]]` — one of multiple sections, run in order## How it works@@ -1516,10 +1522,11 @@ copy = "wt step copy-ignored"Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:```toml-pre-start = [- {copy = "wt step copy-ignored"},- {install = "pnpm install"},-]+[[pre-start]]+copy = "wt step copy-ignored"++[[pre-start]]+install = "pnpm install"```## Dev servers@@ -1553,22 +1560,23 @@ server = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branEach worktree can have its own database. A pipeline sets up the container name and connection string as vars, then later steps and hooks reference them:```toml-post-start = [- { set-vars = """- wt config state vars set \- container='{{ repo }}-{{ branch | sanitize }}-postgres' \- port='{{ ('db-' ~ branch) | hash_port }}' \- db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'- """ },- { db = """- docker run -d --rm \- --name {{ vars.container }} \- -p {{ vars.port }}:5432 \- -e POSTGRES_DB={{ branch | sanitize_db }} \- -e POSTGRES_PASSWORD=dev \- postgres:16- """},-]+[[post-start]]+set-vars = """+wt config state vars set \+ container='{{ repo }}-{{ branch | sanitize }}-postgres' \+ port='{{ ('db-' ~ branch) | hash_port }}' \+ db_url='postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}'+"""++[[post-start]]+db = """+docker run -d --rm \+ --name {{ vars.container }} \+ -p {{ vars.port }}:5432 \+ -e POSTGRES_DB={{ branch | sanitize_db }} \+ -e POSTGRES_PASSWORD=dev \+ postgres:16+"""[post-remove]db-stop = "docker stop {{ vars.container }} 2>/dev/null || true"@@ -1587,15 +1595,17 @@ $ DATABASE_URL=$(wt config state vars get db_url) npm startQuick checks before commit, thorough validation before merge:```toml-pre-commit = [- {lint = "npm run lint"},- {typecheck = "npm run typecheck"},-]+[[pre-commit]]+lint = "npm run lint"++[[pre-commit]]+typecheck = "npm run typecheck"++[[pre-merge]]+test = "npm test"-pre-merge = [- {test = "npm test"},- {build = "npm run build"},-]+[[pre-merge]]+build = "npm run build"```## Target-specific behavior@@ -1628,20 +1638,23 @@ For copying dependencies and caches between worktrees, see [`wt step copy-ignore```tomlpost-merge = "cargo install --path ."-pre-start = [- {install = "npm ci"},- {env = "echo 'PORT={{ branch | hash_port }}' > .env.local"},-]+[[pre-start]]+install = "npm ci"++[[pre-start]]+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"++[[pre-commit]]+format = "cargo fmt -- --check"-pre-commit = [- {format = "cargo fmt -- --check"},- {lint = "cargo clippy -- -D warnings"},-]+[[pre-commit]]+lint = "cargo clippy -- -D warnings"-pre-merge = [- {test = "cargo test"},- {build = "cargo build --release"},-]+[[pre-merge]]+test = "cargo test"++[[pre-merge]]+build = "cargo build --release"[pre-switch]pull = """diff --git a/src/config/commands.rs b/src/config/commands.rsindex 47f9abee4..bac58a910 100644--- a/src/config/commands.rs+++ b/src/config/commands.rs@@ -2,6 +2,40 @@//!//! See `wt hook --help` → "Pipeline Ordering" for user-facing docs.//! See [`HookStep`] and [`CommandConfig`] for the internal model.+//!+//! # TOML representation notes+//!+//! In primitive terms, a hook deserializes from one of three values: a+//! string, a dict, or a list of (string | dict). TOML offers multiple+//! syntaxes for each primitive — `[hook]` section vs. `hook = {...}` inline,+//! `[[hook]]` headers vs. `hook = [{...}]` inline. These are equivalent at+//! the parsed value, so the deserializer sees only the primitive shape.+//!+//! | Primitive | Example | Resulting `steps` |+//! |---|---|---|+//! | string | `hook = "cmd"` | `[Single(unnamed)]` |+//! | dict | `[hook]` + keys, or `hook = {a="...", b="..."}` | `[Concurrent(all entries)]` — always `Concurrent`, even for one entry |+//! | list | `hook = [{a="..."}, "cmd", ...]` | one step per element: string → `Single(unnamed)`; 1-key dict → `Single(named)`; multi-key dict → `Concurrent` |+//!+//! ## Dict-at-top vs. dict-in-list is asymmetric+//!+//! A top-level dict always becomes `Concurrent`. A one-entry dict inside a+//! list becomes `Single(named)` instead (see `map_to_step`). So+//! `{test="..."}` and `[{test="..."}]` have the same command set but+//! different `HookStep` variants. For pre-* hooks this is invisible+//! (everything runs serially anyway); for post-* hooks it controls+//! parallelism.+//!+//! ## `[[hook]]` header form is not a full alternative to pipeline form+//!+//! TOML array-of-tables headers only produce dict elements. A pipeline that+//! mixes anonymous strings with named dicts — e.g.+//! `hook = ["cargo setup", {build="..."}]` — cannot be rewritten as repeated+//! `[[hook]]` blocks without inventing a name for each bare-string step.+//! Naming is user-visible: it changes the step from anonymous `Single` to+//! named `Single`, which affects log file paths+//! (`.../set-vars.log` vs. a positional slot) and hook-selection filtering+//! (`wt hook post-start <name>`).use std::collections::BTreeMap;diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snapindex bdca2d507..0cf7c10d2 100644--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap@@ -162,10 +162,11 @@ 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-pre-merge = [- {test = "cargo test"},- {lint = "cargo clippy"},-]+[[pre-merge]]+test = "cargo test"++[[pre-merge]]+lint = "cargo clippy"```## See alsodiff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snapindex 0e2b4481a..4fad1e51f 100644--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap@@ -150,10 +150,11 @@ 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 [2mpre-merge = [[0m-[107m [0m [2m {test = [0m[2m[32m"cargo test"[0m[2m},[0m-[107m [0m [2m {lint = [0m[2m[32m"cargo clippy"[0m[2m},[0m-[107m [0m [2m][0m+[107m [0m [2m[36m[[pre-merge]][0m+[107m [0m [2mtest = [0m[2m[32m"cargo test"[0m+[107m [0m+[107m [0m [2m[36m[[pre-merge]][0m+[107m [0m [2mlint = [0m[2m[32m"cargo clippy"[0m[1m[32mSee also[0m