Skip to content

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.md
index 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 works
Steps 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.md
index 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 works
Steps 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.rs
index 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 works
Steps 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.rs
index 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 {