Skip to content

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

docs(hook): group template variables by kind and align ordering (#2303)

Maximilian Roos0639b6bf0eb8
diff --git a/docs/content/hook.md b/docs/content/hook.md
index cb1091e77..fa7638b0a 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -114,31 +114,31 @@ Skip all hooks with `--no-hooks`. To run a specific hook when user and project b
Hooks can use template variables that expand at runtime:
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Active branch name |
-| `{{ worktree_path }}` | Active worktree path |
-| `{{ worktree_name }}` | Active worktree directory name |
-| `{{ commit }}` | Active branch HEAD SHA |
-| `{{ short_commit }}` | Active branch HEAD SHA (7 chars) |
-| `{{ upstream }}` | Active branch upstream (if tracking a remote) |
-| `{{ base }}` | Base branch name |
-| `{{ base_worktree_path }}` | Base worktree path |
-| `{{ target }}` | Target branch name |
-| `{{ target_worktree_path }}` | Target worktree path |
-| `{{ cwd }}` | Directory where the hook command runs |
-| `{{ repo }}` | Repository directory name |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ owner }}` | Primary remote owner path (may include subgroups) |
-| `{{ primary_worktree_path }}` | Primary worktree path |
-| `{{ default_branch }}` | Default branch name |
-| `{{ remote }}` | Primary remote name |
-| `{{ remote_url }}` | Remote URL |
-| `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
-| `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
-| `{{ hook_name }}` | Hook command name (if named) |
-| `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |
+| Kind | Variable | Description |
+|------|----------|-------------|
+| active | `{{ branch }}` | Branch name |
+| | `{{ worktree_path }}` | Worktree path |
+| | `{{ worktree_name }}` | Worktree directory name |
+| | `{{ commit }}` | Branch HEAD SHA |
+| | `{{ short_commit }}` | Branch HEAD SHA (7 chars) |
+| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
+| operation | `{{ base }}` | Base branch name |
+| | `{{ base_worktree_path }}` | Base worktree path |
+| | `{{ target }}` | Target branch name |
+| | `{{ target_worktree_path }}` | Target worktree path |
+| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| repo | `{{ repo }}` | Repository directory name |
+| | `{{ repo_path }}` | Absolute path to repository root |
+| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
+| | `{{ primary_worktree_path }}` | Primary worktree path |
+| | `{{ default_branch }}` | Default branch name |
+| | `{{ remote }}` | Primary remote name |
+| | `{{ remote_url }}` | Remote URL |
+| exec | `{{ cwd }}` | Directory where the hook command runs |
+| | `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
+| | `{{ hook_name }}` | Hook command name (if named) |
+| user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |
Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index efb190d03..a5e92eb4c 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -105,31 +105,31 @@ Skip all hooks with `--no-hooks`. To run a specific hook when user and project b
Hooks can use template variables that expand at runtime:
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Active branch name |
-| `{{ worktree_path }}` | Active worktree path |
-| `{{ worktree_name }}` | Active worktree directory name |
-| `{{ commit }}` | Active branch HEAD SHA |
-| `{{ short_commit }}` | Active branch HEAD SHA (7 chars) |
-| `{{ upstream }}` | Active branch upstream (if tracking a remote) |
-| `{{ base }}` | Base branch name |
-| `{{ base_worktree_path }}` | Base worktree path |
-| `{{ target }}` | Target branch name |
-| `{{ target_worktree_path }}` | Target worktree path |
-| `{{ cwd }}` | Directory where the hook command runs |
-| `{{ repo }}` | Repository directory name |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ owner }}` | Primary remote owner path (may include subgroups) |
-| `{{ primary_worktree_path }}` | Primary worktree path |
-| `{{ default_branch }}` | Default branch name |
-| `{{ remote }}` | Primary remote name |
-| `{{ remote_url }}` | Remote URL |
-| `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
-| `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
-| `{{ hook_name }}` | Hook command name (if named) |
-| `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars) |
+| Kind | Variable | Description |
+|------|----------|-------------|
+| active | `{{ branch }}` | Branch name |
+| | `{{ worktree_path }}` | Worktree path |
+| | `{{ worktree_name }}` | Worktree directory name |
+| | `{{ commit }}` | Branch HEAD SHA |
+| | `{{ short_commit }}` | Branch HEAD SHA (7 chars) |
+| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
+| operation | `{{ base }}` | Base branch name |
+| | `{{ base_worktree_path }}` | Base worktree path |
+| | `{{ target }}` | Target branch name |
+| | `{{ target_worktree_path }}` | Target worktree path |
+| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| repo | `{{ repo }}` | Repository directory name |
+| | `{{ repo_path }}` | Absolute path to repository root |
+| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
+| | `{{ primary_worktree_path }}` | Primary worktree path |
+| | `{{ default_branch }}` | Default branch name |
+| | `{{ remote }}` | Primary remote name |
+| | `{{ remote_url }}` | Remote URL |
+| exec | `{{ cwd }}` | Directory where the hook command runs |
+| | `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
+| | `{{ hook_name }}` | Hook command name (if named) |
+| user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars) |
Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 9037b8e4a..88221c4be 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1252,31 +1252,31 @@ Skip all hooks with `--no-hooks`. To run a specific hook when user and project b
Hooks can use template variables that expand at runtime:
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Active branch name |
-| `{{ worktree_path }}` | Active worktree path |
-| `{{ worktree_name }}` | Active worktree directory name |
-| `{{ commit }}` | Active branch HEAD SHA |
-| `{{ short_commit }}` | Active branch HEAD SHA (7 chars) |
-| `{{ upstream }}` | Active branch upstream (if tracking a remote) |
-| `{{ base }}` | Base branch name |
-| `{{ base_worktree_path }}` | Base worktree path |
-| `{{ target }}` | Target branch name |
-| `{{ target_worktree_path }}` | Target worktree path |
-| `{{ cwd }}` | Directory where the hook command runs |
-| `{{ repo }}` | Repository directory name |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ owner }}` | Primary remote owner path (may include subgroups) |
-| `{{ primary_worktree_path }}` | Primary worktree path |
-| `{{ default_branch }}` | Default branch name |
-| `{{ remote }}` | Primary remote name |
-| `{{ remote_url }}` | Remote URL |
-| `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
-| `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
-| `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
-| `{{ hook_name }}` | Hook command name (if named) |
-| `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |
+| Kind | Variable | Description |
+|------|----------|-------------|
+| active | `{{ branch }}` | Branch name |
+| | `{{ worktree_path }}` | Worktree path |
+| | `{{ worktree_name }}` | Worktree directory name |
+| | `{{ commit }}` | Branch HEAD SHA |
+| | `{{ short_commit }}` | Branch HEAD SHA (7 chars) |
+| | `{{ upstream }}` | Branch upstream (if tracking a remote) |
+| operation | `{{ base }}` | Base branch name |
+| | `{{ base_worktree_path }}` | Base worktree path |
+| | `{{ target }}` | Target branch name |
+| | `{{ target_worktree_path }}` | Target worktree path |
+| | `{{ pr_number }}` | PR/MR number (when creating via `pr:N` / `mr:N`) |
+| | `{{ pr_url }}` | PR/MR web URL (when creating via `pr:N` / `mr:N`) |
+| repo | `{{ repo }}` | Repository directory name |
+| | `{{ repo_path }}` | Absolute path to repository root |
+| | `{{ owner }}` | Primary remote owner path (may include subgroups) |
+| | `{{ primary_worktree_path }}` | Primary worktree path |
+| | `{{ default_branch }}` | Default branch name |
+| | `{{ remote }}` | Primary remote name |
+| | `{{ remote_url }}` | Remote URL |
+| exec | `{{ cwd }}` | Directory where the hook command runs |
+| | `{{ hook_type }}` | Hook type being run (e.g. `pre-start`, `pre-merge`) |
+| | `{{ hook_name }}` | Hook command name (if named) |
+| user | `{{ vars.<key> }}` | Per-branch variables from [`wt config state vars`](@/config.md#wt-config-state-vars) |
Bare variables (`branch`, `worktree_path`, `commit`) refer to the branch the operation acts on: the destination for switch/create, the source for merge/remove. `base` and `target` give the other side:
diff --git a/src/config/expansion.rs b/src/config/expansion.rs
index f36a24c76..c86129bff 100644
--- a/src/config/expansion.rs
+++ b/src/config/expansion.rs
@@ -31,20 +31,30 @@ use crate::styling::{
/// Populated by `build_hook_context()` in `command_executor.rs`. `upstream`
/// is conditional on branch tracking configuration but is included here so
/// templates may reference it in any context (guarded by `{% if upstream %}`).
+///
+/// Ordered to match the user-facing help table in `src/cli/mod.rs`
+/// (`## Template variables`): active-context vars first, then repo/remote
+/// metadata, then the always-available portion of execution context (`cwd`).
+/// Operation-context vars (`base`, `target`, `pr_*`) and infrastructure
+/// vars (`hook_type`, `hook_name`) are not in `BASE_VARS` — they're added
+/// per-scope by `hook_extras` and `HOOK_INFRASTRUCTURE_VARS`.
pub const BASE_VARS: &[&str] = &[
- "repo",
- "owner",
+ // Active context
"branch",
- "worktree_name",
- "repo_path",
"worktree_path",
- "default_branch",
- "primary_worktree_path",
+ "worktree_name",
"commit",
"short_commit",
+ "upstream",
+ // Repo / remote metadata
+ "repo",
+ "repo_path",
+ "owner",
+ "primary_worktree_path",
+ "default_branch",
"remote",
"remote_url",
- "upstream",
+ // Execution context (always-available portion)
"cwd",
];
@@ -93,6 +103,11 @@ pub enum ValidationScope {
/// These are the vars injected by callers via `extra_vars` when running a
/// hook. Keeping the mapping in one place means "which vars work in a
/// `post-merge` hook?" is answerable without chasing inline comments.
+///
+/// Each arm's order must be a prefix-ordered subset of the operation-context
+/// block in the user-facing help table (`src/cli/mod.rs`, `## Template
+/// variables`): `base, base_worktree_path, target, target_worktree_path,
+/// pr_number, pr_url`.
fn hook_extras(hook_type: HookType) -> &'static [&'static str] {
use HookType::*;
match hook_type {