Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(alias): clarify which template variables are available in aliases (#2314)
Maximilian Roos31b9b35103ff
diff --git a/docs/content/extending.md b/docs/content/extending.mdindex a495dac9b..d52494cc7 100644--- a/docs/content/extending.md+++ b/docs/content/extending.md@@ -11,7 +11,7 @@ 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 as `wt <name>`. Same template variables as hooks, but triggered manually.+**[Aliases](#aliases)** define reusable commands invoked as `wt <name>`.**[Custom subcommands](#custom-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.@@ -108,7 +108,7 @@ See [Tips & Patterns](@/tips-patterns.md) for more recipes: dev server per workt## Aliases-`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.+`[aliases]` defines commands invoked as `wt <name>`.```toml[aliases]@@ -121,15 +121,17 @@ since-main = "git log --oneline {{ default_branch }}..HEAD"`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).-### Passing values+### Templates-`--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 [Forwarding](#forwarding-positional-arguments)).+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.++`--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)).Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.-### Forwarding positional arguments+### Positional arguments`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command:diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex 37d11df61..07d1cb908 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -4,7 +4,7 @@ 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 as `wt <name>`. Same template variables as hooks, but triggered manually.+**[Aliases](#aliases)** define reusable commands invoked as `wt <name>`.**[Custom subcommands](#custom-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.@@ -101,7 +101,7 @@ See [Tips & Patterns](https://worktrunk.dev/tips-patterns/) for more recipes: de## Aliases-`[aliases]` defines commands invoked as `wt <name>`. Templates and approvals behave like hooks.+`[aliases]` defines commands invoked as `wt <name>`.```toml[aliases]@@ -117,15 +117,17 @@ wt open`wt <name>` resolves to a built-in first, then an alias, then a [custom subcommand](#custom-subcommands).-### Passing values+### Templates-`--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 [Forwarding](#forwarding-positional-arguments)).+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.++`--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)).Built-in variables can be overridden: `--branch=foo` sets `{{ branch }}` inside the template — the worktree's actual branch doesn't move.Hyphens in keys become underscores: `--my-var=x` sets `{{ my_var }}`.-### Forwarding positional arguments+### Positional arguments`{{ args }}` renders as a space-joined, shell-escaped string — ready to splice into a command: