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.mdindex 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.mdindex 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 filesdiff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 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.mdindex 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 filesdiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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 filesdiff --git a/src/config/commands.rs b/src/config/commands.rsindex 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