Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: rewrite pipeline ordering with progressive examples (#1756)
Maximilian Roosd738ff1c3959
diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 0f47a226f..fbdefacbc 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -310,28 +310,40 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for<span class="badge-experimental"></span>-By default, all commands in a `post-*` hook run concurrently in the background. When one command depends on another — `npm run build` needs `npm install` to finish first — use a list instead of a table:+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-[hooks]-post-start = [- { install = "npm install" },- { build = "npm run build", lint = "npm run lint" }-]+post-start = "npm install"```-The list runs steps in order. Each step is either a string (single command) or a map (named commands). Single-entry maps run one command; multi-entry maps run their commands concurrently. The TOML data structure encodes the execution model directly:+Most hooks are a map of named commands, which run concurrently:-- **String** — single command-- **Map** (table) — concurrent commands-- **List** (array) — serial pipeline+```toml+[post-start]+install = "npm install"+build = "npm run build"+lint = "npm run lint"+```-The entire pipeline runs in the background as one process. Anonymous steps work too:+When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:```toml-post-start = ["npm install", "npm run build"]+# 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" }+]```+In summary:++- **String** — one command+- **Map** of `name = "command"` pairs — run concurrently+- **List** of maps — run in order+## How it worksSteps are chained with `&&` in a compound shell command, so a failing step skips all later steps. A multi-entry map spawns its commands as background processes and waits for all to complete before the next step.diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex a0c4d6166..27662272f 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -301,28 +301,40 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for[experimental]-By default, all commands in a `post-*` hook run concurrently in the background. When one command depends on another — `npm run build` needs `npm install` to finish first — use a list instead of a table:+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-[hooks]-post-start = [- { install = "npm install" },- { build = "npm run build", lint = "npm run lint" }-]+post-start = "npm install"```-The list runs steps in order. Each step is either a string (single command) or a map (named commands). Single-entry maps run one command; multi-entry maps run their commands concurrently. The TOML data structure encodes the execution model directly:+Most hooks are a map of named commands, which run concurrently:-- **String** — single command-- **Map** (table) — concurrent commands-- **List** (array) — serial pipeline+```toml+[post-start]+install = "npm install"+build = "npm run build"+lint = "npm run lint"+```-The entire pipeline runs in the background as one process. Anonymous steps work too:+When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:```toml-post-start = ["npm install", "npm run build"]+# 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" }+]```+In summary:++- **String** — one command+- **Map** of `name = "command"` pairs — run concurrently+- **List** of maps — run in order+## How it worksSteps are chained with `&&` in a compound shell command, so a failing step skips all later steps. A multi-entry map spawns its commands as background processes and waits for all to complete before the next step.diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex fcd188084..ce738eeff 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1399,28 +1399,40 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for# Pipeline Ordering [experimental]-By default, all commands in a `post-*` hook run concurrently in the background. When one command depends on another — `npm run build` needs `npm install` to finish first — use a list instead of a table:+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-[hooks]-post-start = [- { install = "npm install" },- { build = "npm run build", lint = "npm run lint" }-]+post-start = "npm install"```-The list runs steps in order. Each step is either a string (single command) or a map (named commands). Single-entry maps run one command; multi-entry maps run their commands concurrently. The TOML data structure encodes the execution model directly:+Most hooks are a map of named commands, which run concurrently:-- **String** — single command-- **Map** (table) — concurrent commands-- **List** (array) — serial pipeline+```toml+[post-start]+install = "npm install"+build = "npm run build"+lint = "npm run lint"+```-The entire pipeline runs in the background as one process. Anonymous steps work too:+When one command depends on another — `npm run build` needs `npm install` to finish first — use a list to run steps in order:```toml-post-start = ["npm install", "npm run build"]+# 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" }+]```+In summary:++- **String** — one command+- **Map** of `name = "command"` pairs — run concurrently+- **List** of maps — run in order+## How it worksSteps are chained with `&&` in a compound shell command, so a failing step skips all later steps. A multi-entry map spawns its commands as background processes and waits for all to complete before the next step.diff --git a/src/config/commands.rs b/src/config/commands.rsindex ea23bf42a..2b1013c7e 100644--- a/src/config/commands.rs+++ b/src/config/commands.rs@@ -179,6 +179,9 @@ impl<'de> Deserialize<'de> for CommandConfig {D: serde::Deserializer<'de>,{/// An entry in a pipeline list: either a string or a map of named commands.+ ///+ /// Anonymous strings work but are intentionally undocumented — they+ /// complicate the explanation without adding much over single-entry maps.#[derive(Deserialize)]#[serde(untagged)]enum PipelineEntry {