Skip to content

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

docs(aliases): teach [[aliases.NAME]] pipeline blocks (#2144)

Maximilian Roos3f44cb568aba
diff --git a/docs/content/step.md b/docs/content/step.md
index 6855d8bf9..0afc19104 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -842,6 +842,23 @@ git fetch --all --prune && wt step for-each -- '
{{ terminal(cmd="wt step up") }}
+Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.
+
+```toml
+# .config/wt.toml
+[[aliases.release]]
+test = "cargo test"
+
+[[aliases.release]]
+build = "cargo build --release"
+package = "cargo package --no-verify"
+
+[[aliases.release]]
+publish = "cargo publish"
+```
+
+Here `test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.
+
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 1119ca8fe..453d29909 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -896,6 +896,23 @@ git fetch --all --prune && wt step for-each -- '
$ wt step up
```
+Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.
+
+```toml
+# .config/wt.toml
+[[aliases.release]]
+test = "cargo test"
+
+[[aliases.release]]
+build = "cargo build --release"
+package = "cargo package --no-verify"
+
+[[aliases.release]]
+publish = "cargo publish"
+```
+
+Here `test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.
+
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](https://worktrunk.dev/hook/#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 7b7d540a1..f8d884b4a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1178,6 +1178,23 @@ git fetch --all --prune && wt step for-each -- '
$ wt step up
```
+Multi-step aliases run commands in order using `[[aliases.NAME]]` blocks. Each block is one step; multiple keys within a block run concurrently.
+
+```toml
+# .config/wt.toml
+[[aliases.release]]
+test = "cargo test"
+
+[[aliases.release]]
+build = "cargo build --release"
+package = "cargo package --no-verify"
+
+[[aliases.release]]
+publish = "cargo publish"
+```
+
+Here `test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps.
+
When defined in both user and project config, both run — user first, then project. Project-config aliases require [command approval](@/hook.md#wt-hook-approvals) on first run, same as project hooks. User-config aliases are trusted.
Inside an alias body, an inner `wt switch` (or `wt switch --create`) passes its `cd` through to the parent shell, so an alias wrapping `wt switch --create` lands the shell in the new worktree just like running it directly.
diff --git a/src/config/project.rs b/src/config/project.rs
index ccf298beb..f31f53559 100644
--- a/src/config/project.rs
+++ b/src/config/project.rs
@@ -172,12 +172,11 @@ pub struct ProjectConfig {
/// \[experimental\] Command aliases for `wt step <name>`.
///
- /// Each alias maps a name to one or more command templates. All hook
- /// template variables are available (e.g., `{{ branch }}`, `{{ worktree_path }}`).
- ///
- /// Uses `CommandConfig` for consistency with hooks. This means the
- /// named-table format (`[aliases.deploy] build = "..." run = "..."`)
- /// technically works, but the single-string format is the expected usage.
+ /// Each alias maps a name to a [`CommandConfig`] — a string for a single
+ /// command, a named table (`[aliases.NAME]`) for concurrent commands, or
+ /// `[[aliases.NAME]]` blocks for sequential pipeline steps. All hook
+ /// template variables are available (e.g., `{{ branch }}`,
+ /// `{{ worktree_path }}`).
///
/// ```toml
/// [aliases]
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 5af0090a2..f8fe8142e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -130,6 +130,21 @@ Multi-line aliases work too. This up alias fetches all remotes and rebas
  wt step up
+Multi-step aliases run commands in order using [[aliases.NAME]] blocks. Each block is one step; multiple keys within a block run concurrently.
+
+  # .config/wt.toml
+  [[aliases.release]]
+  test = "cargo test"
+ 
+  [[aliases.release]]
+  build = "cargo build --release"
+  package = "cargo package --no-verify"
+ 
+  [[aliases.release]]
+  publish = "cargo publish"
+
+Here test runs first, then build and package run together, then publish runs last. A step failure aborts the remaining steps.
+
When defined in both user and project config, both run — user first, then project. Project-config aliases require command approval on first run, same as project hooks. User-config aliases are trusted.
Inside an alias body, an inner wt switch (or wt switch --create) passes its cd through to the parent shell, so an alias wrapping wt switch --create lands the shell in the new worktree just like running it directly.