Skip to content

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.md
index 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 variables
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 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 {{ bran
Each 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
```toml
post-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.md
index 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 locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
-pre-merge = [
- {test = "cargo test"},
- {lint = "cargo clippy"},
-]
+[[pre-merge]]
+test = "cargo test"
+
+[[pre-merge]]
+lint = "cargo clippy"
```
## See also
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 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 whi
Each 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.md
index 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 variables
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 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 {{ bran
Each 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 start
Quick 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
```toml
post-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.md
index 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 locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
-pre-merge = [
- {test = "cargo test"},
- {lint = "cargo clippy"},
-]
+[[pre-merge]]
+test = "cargo test"
+
+[[pre-merge]]
+lint = "cargo clippy"
```
## Command reference
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 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 whi
Each worktree can have its own isolated database. A pipeline sets up names and ports as [vars](https://worktrunk.dev/config/#wt-config-state-vars), then later steps and hooks reference them:
```toml
-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.rs
index 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 locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
-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 {{ bran
Each 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 start
Quick 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
```toml
post-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.rs
index 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.snap
index 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 locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run `wt merge`, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
```toml
-pre-merge = [
- {test = "cargo test"},
- {lint = "cargo clippy"},
-]
+[[pre-merge]]
+test = "cargo test"
+
+[[pre-merge]]
+lint = "cargo clippy"
```
## See also
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 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 locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run wt merge, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
-  pre-merge = [
-   {test = "cargo test"},
-   {lint = "cargo clippy"},
-  ]
+  [[pre-merge]]
+  test = "cargo test"
+ 
+  [[pre-merge]]
+  lint = "cargo clippy"
See also