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.mdindex 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 bHooks 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.mdindex 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 bHooks 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.rsindex 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 bHooks 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.rsindex 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 {