Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: add Extending Worktrunk page (#2079)
Maximilian Roose2fff694a542
diff --git a/docs/content/extending.md b/docs/content/extending.mdnew file mode 100644index 000000000..1fa0ff341--- /dev/null+++ b/docs/content/extending.md@@ -0,0 +1,133 @@+++++title = "Extending Worktrunk"+description = "Three ways to add custom behavior: hooks for lifecycle automation, aliases for reusable commands, and external subcommands for standalone tools."+weight = 21++[extra]+group = "Reference"++++++Worktrunk has three extension mechanisms.++**[Hooks](#hooks)** run shell commands at lifecycle events — creating a worktree, merging, removing. They're configured in TOML and run automatically.++**[Aliases](#aliases)** define reusable commands invoked via `wt step <name>`. Same template variables as hooks, but triggered manually.++**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.++| | Hooks | Aliases | External subcommands |+|---|---|---|---|+| **Trigger** | Automatic (lifecycle events) | Manual (`wt step <name>`) | Manual (`wt <name>`) |+| **Defined in** | TOML config | TOML config | Any executable on `PATH` |+| **Template variables** | Yes | Yes | No |+| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |+| **Language** | Shell commands | Shell commands | Any |++## Hooks++Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:++| Event | `pre-` (blocking) | `post-` (background) |+|-------|-------------------|---------------------|+| **switch** | `pre-switch` | `post-switch` |+| **start** | `pre-start` | `post-start` |+| **commit** | `pre-commit` | `post-commit` |+| **merge** | `pre-merge` | `post-merge` |+| **remove** | `pre-remove` | `post-remove` |++`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](@/hook.md#wt-hook-approvals) on first run++Three formats, from simplest to most expressive:++```toml+# Single command+pre-start = "npm ci"+```++```toml+# Named commands (concurrent for post-*, serial for pre-*)+[post-start]+server = "npm start"+watcher = "npm run watch"+```++```toml+# Pipeline: steps run in order, commands within a step run concurrently+post-start = [+ "npm ci",+ { server = "npm start", build = "npm run build" }+]+```++### Template variables++Hook commands are templates. Variables expand at execution time:++```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.++## Aliases++Aliases are custom commands invoked via `wt step <name>`. They share the same template variables and approval model as hooks.++```toml+# .config/wt.toml+[aliases]+deploy = "make deploy BRANCH={{ branch }}"+open = "open http://localhost:{{ branch | hash_port }}"+```++{{ terminal(cmd="wt step deploy|||wt step deploy --dry-run|||wt step deploy --var env=staging") }}++When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval, same as project hooks.++Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.++See [`wt step` — Aliases](@/step.md#aliases) for the full reference.++## External subcommands++<span class="badge-experimental"></span>++Any executable named `wt-<name>` on `PATH` becomes available as `wt <name>` — the same pattern git uses for `git-foo`. Built-in commands always take precedence.++{{ terminal(cmd="wt sync origin # runs: wt-sync origin|||wt -C /tmp/repo sync # -C is forwarded as the child's working directory") }}++Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.++If nothing matches — no built-in, no nested subcommand, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 5990908c7..09fd3dcf4 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -31,14 +31,6 @@ test = "cargo test --features {{ vars.features | default('default') }}"See [`wt step` aliases](@/step.md#aliases) for scoping, approval, and reference.-## External subcommands `[experimental]`--Drop a `wt-<name>` binary anywhere on `PATH` and `wt <name>` will run it — mirroring how `git foo` finds `git-foo`. Use this to ship third-party extensions without patching worktrunk itself.--{{ terminal(cmd="wt sync origin # runs: wt-sync origin|||wt -C /tmp/repo sync # `-C` is forwarded as the child's cwd") }}--Built-in commands always take precedence, so an external `wt-switch` cannot shadow `wt switch`. Arguments after the name are passed through verbatim (including `--help`), and the child's exit code is propagated unchanged. If nothing matches — no built-in, no nested subcommand, no `wt-<name>` — wt prints a git-style `'foo' is not a wt command` error with a typo suggestion drawn from the built-in command list.-## Per-branch variables`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses:diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdnew file mode 100644index 000000000..3d4556dcc--- /dev/null+++ b/skills/worktrunk/reference/extending.md@@ -0,0 +1,133 @@+# Extending Worktrunk++Worktrunk has three extension mechanisms.++**[Hooks](#hooks)** run shell commands at lifecycle events — creating a worktree, merging, removing. They're configured in TOML and run automatically.++**[Aliases](#aliases)** define reusable commands invoked via `wt step <name>`. Same template variables as hooks, but triggered manually.++**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.++| | Hooks | Aliases | External subcommands |+|---|---|---|---|+| **Trigger** | Automatic (lifecycle events) | Manual (`wt step <name>`) | Manual (`wt <name>`) |+| **Defined in** | TOML config | TOML config | Any executable on `PATH` |+| **Template variables** | Yes | Yes | No |+| **Shareable via repo** | `.config/wt.toml` | `.config/wt.toml` | Distribute the binary |+| **Language** | Shell commands | Shell commands | Any |++## Hooks++Hooks are shell commands that run at key points in the worktree lifecycle. Ten hooks cover five events:++| Event | `pre-` (blocking) | `post-` (background) |+|-------|-------------------|---------------------|+| **switch** | `pre-switch` | `post-switch` |+| **start** | `pre-start` | `post-start` |+| **commit** | `pre-commit` | `post-commit` |+| **merge** | `pre-merge` | `post-merge` |+| **remove** | `pre-remove` | `post-remove` |++`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/hook/#wt-hook-approvals) on first run++Three formats, from simplest to most expressive:++```toml+# Single command+pre-start = "npm ci"+```++```toml+# Named commands (concurrent for post-*, serial for pre-*)+[post-start]+server = "npm start"+watcher = "npm run watch"+```++```toml+# Pipeline: steps run in order, commands within a step run concurrently+post-start = [+ "npm ci",+ { server = "npm start", build = "npm run build" }+]+```++### Template variables++Hook commands are templates. Variables expand at execution time:++```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.++## Aliases++Aliases are custom commands invoked via `wt step <name>`. They share the same template variables and approval model as hooks.++```toml+# .config/wt.toml+[aliases]+deploy = "make deploy BRANCH={{ branch }}"+open = "open http://localhost:{{ branch | hash_port }}"+```++```bash+$ wt step deploy+$ wt step deploy --dry-run+$ wt step deploy --var env=staging+```++When both user and project config define the same alias name, both run — user first, then project. Project-config aliases require approval, same as project hooks.++Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.++See [`wt step` — Aliases](https://worktrunk.dev/step/#aliases) for the full reference.++## External subcommands++[experimental]++Any executable named `wt-<name>` on `PATH` becomes available as `wt <name>` — the same pattern git uses for `git-foo`. Built-in commands always take precedence.++```bash+$ wt sync origin # runs: wt-sync origin+$ wt -C /tmp/repo sync # -C is forwarded as the child's working directory+```++Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.++If nothing matches — no built-in, no nested subcommand, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.mdindex ae820c81c..64c7a696b 100644--- a/skills/worktrunk/reference/tips-patterns.md+++ b/skills/worktrunk/reference/tips-patterns.md@@ -28,17 +28,6 @@ test = "cargo test --features {{ vars.features | default('default') }}"See [`wt step` aliases](https://worktrunk.dev/step/#aliases) for scoping, approval, and reference.-## External subcommands `[experimental]`--Drop a `wt-<name>` binary anywhere on `PATH` and `wt <name>` will run it — mirroring how `git foo` finds `git-foo`. Use this to ship third-party extensions without patching worktrunk itself.--```bash-$ wt sync origin # runs: wt-sync origin-$ wt -C /tmp/repo sync # `-C` is forwarded as the child's cwd-```--Built-in commands always take precedence, so an external `wt-switch` cannot shadow `wt switch`. Arguments after the name are passed through verbatim (including `--help`), and the child's exit code is propagated unchanged. If nothing matches — no built-in, no nested subcommand, no `wt-<name>` — wt prints a git-style `'foo' is not a wt command` error with a typo suggestion drawn from the built-in command list.-## Per-branch variables`wt config state vars` holds state per branch, accessible from templates (`{{ vars.key }}`) and the CLI. Some uses: