Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(hook): consolidate pipeline forms into one section (#2333)

Maximilian Roosf0152a5a0d56
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 3cace0a60..7692ef18c 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -23,7 +23,7 @@ Worktrunk has three extension mechanisms.
| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
| **Language** | Shell commands | Shell commands | Any |
-Hooks and aliases share the TOML config file, the [template engine](@/hook.md#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](@/hook.md#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
+Hooks and aliases share the TOML config file, the [template engine](@/hook.md#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](@/hook.md#hook-forms) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
## Hooks
@@ -97,7 +97,7 @@ Tokens after `--` forward unconditionally, bypassing any binding. Writing `wt de
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](@/hook.md#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
+`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](@/hook.md#hook-forms) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
```toml
[[aliases.release]]
diff --git a/docs/content/hook.md b/docs/content/hook.md
index b9de7f6b6..d3660812f 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -68,7 +68,11 @@ Manage approvals with `wt config approvals add` and `wt config approvals clear`.
# Configuration
-Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format. Hooks take one of three forms.
+Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format.
+
+## Hook forms
+
+Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
@@ -84,7 +88,7 @@ server = "npm run dev"
watch = "npm run watch"
```
-A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:
+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
[[post-start]]
@@ -97,6 +101,8 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
+Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
+
Table form for pre-* hooks is deprecated and its behavior will change in a future version — use `[[hook]]` blocks instead.
## Project vs user hooks
@@ -244,59 +250,6 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Pipeline Ordering
-
-<span class="badge-experimental"></span>
-
-By default, all commands in a `post-*` hook run concurrently in the background. The TOML type determines execution order. In the simplest case, a string runs one command:
-
-```toml
-post-start = "npm install"
-```
-
-Most hooks are a map of named commands, which run concurrently:
-
-```toml
-[post-start]
-install = "npm install"
-build = "npm run build"
-lint = "npm run lint"
-```
-
-When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order. A failing step aborts the rest of the pipeline:
-
-```toml
-# 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, the bracket count tracks the shape:
-
-- `post-start = "npm install"` — one command
-- `[post-start]` — one section of concurrent commands
-- `[[post-start]]` — one of multiple sections, run in order
-
-## When to use pipelines
-
-Most hooks don't need pipelines. A table of concurrent post-start commands is fine when they're independent:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-copy = "wt step copy-ignored"
-```
-
-Pipelines matter when there's a dependency chain — typically setup steps that must complete before other tasks can start. Common pattern: install dependencies, then run build + dev server concurrently.
-
# Designing Effective Hooks
## Copying untracked files
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index bf64d82be..6e432b40a 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -16,7 +16,7 @@ Worktrunk has three extension mechanisms.
| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |
| **Language** | Shell commands | Shell commands | Any |
-Hooks and aliases share the TOML config file, the [template engine](https://worktrunk.dev/hook/#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](https://worktrunk.dev/hook/#pipeline-ordering) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
+Hooks and aliases share the TOML config file, the [template engine](https://worktrunk.dev/hook/#template-variables) (variables, filters, and functions), the [`[[block]]` pipeline syntax](https://worktrunk.dev/hook/#hook-forms) (blocks run in order, keys within a block run concurrently), and the approval model: user config is trusted; project config requires approval on first run. When both sources define the same name, both run — user first.
## Hooks
@@ -101,7 +101,7 @@ wt config alias dry-run deploy -- --env=staging
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](https://worktrunk.dev/hook/#pipeline-ordering) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
+`[[aliases.NAME]]` defines a pipeline using the [same `[[block]]` semantics as hooks](https://worktrunk.dev/hook/#hook-forms) — blocks run in order, keys within a block run concurrently, a step failure aborts the remainder:
```toml
[[aliases.release]]
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index b57e92cee..afd692673 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -59,7 +59,11 @@ Manage approvals with `wt config approvals add` and `wt config approvals clear`.
# Configuration
-Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format. Hooks take one of three forms.
+Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format.
+
+## Hook forms
+
+Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
@@ -75,7 +79,7 @@ server = "npm run dev"
watch = "npm run watch"
```
-A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:
+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
[[post-start]]
@@ -88,6 +92,8 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
+Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
+
Table form for pre-* hooks is deprecated and its behavior will change in a future version — use `[[hook]]` blocks instead.
## Project vs user hooks
@@ -245,57 +251,6 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Pipeline Ordering [experimental]
-
-By default, all commands in a `post-*` hook run concurrently in the background. The TOML type determines execution order. In the simplest case, a string runs one command:
-
-```toml
-post-start = "npm install"
-```
-
-Most hooks are a map of named commands, which run concurrently:
-
-```toml
-[post-start]
-install = "npm install"
-build = "npm run build"
-lint = "npm run lint"
-```
-
-When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order. A failing step aborts the rest of the pipeline:
-
-```toml
-# 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, the bracket count tracks the shape:
-
-- `post-start = "npm install"` — one command
-- `[post-start]` — one section of concurrent commands
-- `[[post-start]]` — one of multiple sections, run in order
-
-## When to use pipelines
-
-Most hooks don't need pipelines. A table of concurrent post-start commands is fine when they're independent:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-copy = "wt step copy-ignored"
-```
-
-Pipelines matter when there's a dependency chain — typically setup steps that must complete before other tasks can start. Common pattern: install dependencies, then run build + dev server concurrently.
-
# Designing Effective Hooks
## Copying untracked files
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 598797205..bf1c7390d 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1200,7 +1200,11 @@ Manage approvals with `wt config approvals add` and `wt config approvals clear`.
# Configuration
-Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format. Hooks take one of three forms.
+Hooks can be defined in project config (`.config/wt.toml`) or user config (`~/.config/worktrunk/config.toml`). Both use the same format.
+
+## Hook forms
+
+Hooks take one of three forms, determined by their TOML shape.
A string is a single command:
@@ -1216,7 +1220,7 @@ server = "npm run dev"
watch = "npm run watch"
```
-A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently:
+A pipeline is a sequence of `[[hook]]` blocks run in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline:
```toml
[[post-start]]
@@ -1229,6 +1233,8 @@ server = "npm run dev"
Here `install` runs first, then `build` and `server` run together.
+Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependency chain — typically setup that must complete before later steps, like installing dependencies before running a build and dev server concurrently.
+
Table form for pre-* hooks is deprecated and its behavior will change in a future version — use `[[hook]]` blocks instead.
## Project vs user hooks
@@ -1386,57 +1392,6 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Pipeline Ordering [experimental]
-
-By default, all commands in a `post-*` hook run concurrently in the background. The TOML type determines execution order. In the simplest case, a string runs one command:
-
-```toml
-post-start = "npm install"
-```
-
-Most hooks are a map of named commands, which run concurrently:
-
-```toml
-[post-start]
-install = "npm install"
-build = "npm run build"
-lint = "npm run lint"
-```
-
-When one command depends on another — `npm run build` needs `npm install` to finish first — use `[[hook]]` blocks to run steps in order. A failing step aborts the rest of the pipeline:
-
-```toml
-# 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, the bracket count tracks the shape:
-
-- `post-start = "npm install"` — one command
-- `[post-start]` — one section of concurrent commands
-- `[[post-start]]` — one of multiple sections, run in order
-
-## When to use pipelines
-
-Most hooks don't need pipelines. A table of concurrent post-start commands is fine when they're independent:
-
-```toml
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
-copy = "wt step copy-ignored"
-```
-
-Pipelines matter when there's a dependency chain — typically setup steps that must complete before other tasks can start. Common pattern: install dependencies, then run build + dev server concurrently.
-
# Designing Effective Hooks
## Copying untracked files
diff --git a/src/config/commands.rs b/src/config/commands.rs
index 6d318f14a..ce80f42bc 100644
--- a/src/config/commands.rs
+++ b/src/config/commands.rs
@@ -1,6 +1,6 @@
//! Command configuration types for hook pipelines.
//!
-//! See `wt hook --help` → "Pipeline Ordering" for user-facing docs.
+//! See `wt hook --help` → "Hook forms" for user-facing docs.
//! See [`HookStep`] and [`CommandConfig`] for the internal model.
//!
//! # TOML representation notes