Skip to content

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

docs(extending): consolidate overlap with hook.md and within aliases (#2315)

Maximilian Roosa77edaf0a875
diff --git a/docs/content/extending.md b/docs/content/extending.md
index 58f2ae0d6..adbcfc7e8 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -23,6 +23,8 @@ 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), the `[[block]]` pipeline syntax (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
Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:
@@ -37,74 +39,18 @@ Hooks are shell commands that run at key points in the worktree lifecycle. Ten h
`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background.
-### Configuration
-
-Hooks live in two places:
-
-- **User config** (`~/.config/worktrunk/config.toml`) — personal, applies everywhere, trusted
-- **Project config** (`.config/wt.toml`) — shared with the team, requires [approval](@/config.md#wt-config-approvals) on first run
-
-Three formats, from simplest to most expressive.
-
-A single command as a string:
-
-```toml
-pre-start = "npm ci"
-```
-
-A named table runs commands concurrently for `post-*` hooks and serially for `pre-*`:
-
```toml
-[post-start]
-server = "npm start"
-watcher = "npm run watch"
-```
-
-An array of tables is a pipeline — blocks run in order, commands within a block run concurrently:
-
-```toml
-[[post-start]]
-install = "npm ci"
-
-[[post-start]]
-server = "npm start"
-build = "npm run build"
-```
-
-### Template variables
-
-Hook commands are templates. Variables expand at execution time:
+[pre-start]
+deps = "npm ci"
-```toml
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
-env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
-```
-
-Core variables include `branch`, `worktree_path`, `commit`, `repo`, `default_branch`, and context-dependent ones like `target` during merge. Filters like `sanitize`, `hash_port`, and `sanitize_db` transform values for specific uses.
-
-See [`wt hook`](@/hook.md#template-variables) for the full variable and filter reference.
-
-### Common patterns
-
-```toml
-# .config/wt.toml
-
-# Install dependencies when creating a worktree
-[pre-start]
-deps = "npm ci"
-# Run tests before merging
[pre-merge]
test = "npm test"
-lint = "npm run lint"
-
-# Dev server per worktree on a deterministic port
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
```
-See [Tips & Patterns](@/tips-patterns.md) for more recipes: dev server per worktree, database per worktree, tmux sessions, Caddy subdomain routing.
+See [`wt hook`](@/hook.md) for the full configuration reference — TOML forms, template variables and filters, and built-in recipes (dev server per worktree, database per worktree, progressive validation). [Tips & Patterns](@/tips-patterns.md) has more.
## Aliases
@@ -123,7 +69,7 @@ since-main = "git log --oneline {{ default_branch }}..HEAD"
### Templates
-Templates expand with variables for the current worktree and repo — `{{ branch }}`, `{{ worktree_path }}`, `{{ commit }}`, `{{ repo }}`, `{{ default_branch }}`, `{{ cwd }}`, per-branch `{{ vars.<key> }}` — plus `{{ args }}` for positional CLI arguments. Hook operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress. See [`wt hook`](@/hook.md#template-variables) for the full reference.
+Alias templates have access to the full [variable and filter reference](@/hook.md#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress.
`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Positional arguments](#positional-arguments)).
@@ -155,7 +101,7 @@ Tokens after `--` forward unconditionally, bypassing any binding. `wt deploy --
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.
+`[[aliases.NAME]]` defines a pipeline using the same `[[block]]` semantics as hooks:
```toml
[[aliases.release]]
@@ -169,13 +115,11 @@ package = "cargo package --no-verify"
publish = "cargo publish {{ args }}"
```
-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
-
-### Sources and approval
+A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
-When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.
+### Changing directory
-An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.
+`wt` commands that change the parent shell's directory — `wt switch`, `wt merge` (leaving the removed source), `wt remove` of the current worktree — still do so when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so `cd`, `export`, and similar commands only affect that subshell.
### Recipe: rebase every worktree onto its upstream
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 808306e57..8005d46f6 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -16,6 +16,8 @@ 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), the `[[block]]` pipeline syntax (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
Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:
@@ -30,74 +32,18 @@ Hooks are shell commands that run at key points in the worktree lifecycle. Ten h
`pre-*` hooks block — failure aborts the operation. `post-*` hooks run in the background.
-### Configuration
-
-Hooks live in two places:
-
-- **User config** (`~/.config/worktrunk/config.toml`) — personal, applies everywhere, trusted
-- **Project config** (`.config/wt.toml`) — shared with the team, requires [approval](https://worktrunk.dev/config/#wt-config-approvals) on first run
-
-Three formats, from simplest to most expressive.
-
-A single command as a string:
-
-```toml
-pre-start = "npm ci"
-```
-
-A named table runs commands concurrently for `post-*` hooks and serially for `pre-*`:
-
```toml
-[post-start]
-server = "npm start"
-watcher = "npm run watch"
-```
-
-An array of tables is a pipeline — blocks run in order, commands within a block run concurrently:
-
-```toml
-[[post-start]]
-install = "npm ci"
-
-[[post-start]]
-server = "npm start"
-build = "npm run build"
-```
-
-### Template variables
-
-Hook commands are templates. Variables expand at execution time:
+[pre-start]
+deps = "npm ci"
-```toml
[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
-env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
-```
-
-Core variables include `branch`, `worktree_path`, `commit`, `repo`, `default_branch`, and context-dependent ones like `target` during merge. Filters like `sanitize`, `hash_port`, and `sanitize_db` transform values for specific uses.
-
-See [`wt hook`](https://worktrunk.dev/hook/#template-variables) for the full variable and filter reference.
-
-### Common patterns
-
-```toml
-# .config/wt.toml
-
-# Install dependencies when creating a worktree
-[pre-start]
-deps = "npm ci"
-# Run tests before merging
[pre-merge]
test = "npm test"
-lint = "npm run lint"
-
-# Dev server per worktree on a deterministic port
-[post-start]
-server = "npm run dev -- --port {{ branch | hash_port }}"
```
-See [Tips & Patterns](https://worktrunk.dev/tips-patterns/) for more recipes: dev server per worktree, database per worktree, tmux sessions, Caddy subdomain routing.
+See [`wt hook`](https://worktrunk.dev/hook/) for the full configuration reference — TOML forms, template variables and filters, and built-in recipes (dev server per worktree, database per worktree, progressive validation). [Tips & Patterns](https://worktrunk.dev/tips-patterns/) has more.
## Aliases
@@ -119,7 +65,7 @@ wt open
### Templates
-Templates expand with variables for the current worktree and repo — `{{ branch }}`, `{{ worktree_path }}`, `{{ commit }}`, `{{ repo }}`, `{{ default_branch }}`, `{{ cwd }}`, per-branch `{{ vars.<key> }}` — plus `{{ args }}` for positional CLI arguments. Hook operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress. See [`wt hook`](https://worktrunk.dev/hook/#template-variables) for the full reference.
+Alias templates have access to the full [variable and filter reference](https://worktrunk.dev/hook/#template-variables), plus `{{ args }}` for positional CLI arguments. Operation-context variables (`target`, `base`, `pr_number`) aren't populated in aliases since there's no operation in progress.
`--KEY=VALUE` (or `--KEY VALUE`) binds `KEY` whenever `{{ KEY }}` appears in the template — `wt deploy --env=staging` sets `{{ env }}` to `staging`. Everything else joins `{{ args }}` (see [Positional arguments](#positional-arguments)).
@@ -159,7 +105,7 @@ wt config alias dry-run deploy -- --env=staging
### Multi-step pipelines
-`[[aliases.NAME]]` defines a pipeline. Each block runs serially; keys within a block run concurrently.
+`[[aliases.NAME]]` defines a pipeline using the same `[[block]]` semantics as hooks:
```toml
[[aliases.release]]
@@ -173,13 +119,11 @@ package = "cargo package --no-verify"
publish = "cargo publish {{ args }}"
```
-`test` runs first, then `build` and `package` run together, then `publish` runs last. A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
-
-### Sources and approval
+A step failure aborts the remaining steps. Every step sees the same `{{ args }}` and bound variables — `wt release -- --dry-run` forwards `--dry-run` to `publish` without affecting earlier steps.
-When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval on first run, same as project hooks. User-config aliases are trusted.
+### Changing directory
-An alias that calls `wt switch` (or `wt switch --create`) changes the parent shell's directory, just like running `wt switch` directly.
+`wt` commands that change the parent shell's directory — `wt switch`, `wt merge` (leaving the removed source), `wt remove` of the current worktree — still do so when invoked from an alias; the Worktrunk shell integration propagates the change through. Other shell state doesn't persist: the alias runs in a subshell, so `cd`, `export`, and similar commands only affect that subshell.
### Recipe: rebase every worktree onto its upstream