Skip to content

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

docs: consolidate template variables reference into hook.md (#544)

Maximilian Roos6a4aa35e7e9c
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index eddf1dc39..33cd1e1cc 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -523,17 +523,15 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# Named commands appear in output, making it easier to identify failures.
# ============================================================================
-# Template Variables
+# Template Variables — see https://worktrunk.dev/hook/#template-variables
# ============================================================================
-# All hooks support these variables:
+# Common variables:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
# {{ main_worktree_path }} - Absolute path to main worktree
# {{ default_branch }} - Default branch name (e.g., "main")
-#
-# Merge hooks (pre-commit, pre-merge, post-merge) also support:
-# {{ target }} - Target branch for the merge
+# {{ target }} - Target branch (merge hooks only)
#
# Filters:
# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index b127a0016..23a6b5b93 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -150,8 +150,6 @@ Hooks can use template variables that expand at runtime:
See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`). These still work but emit warnings.
-
### Filters
Templates support Jinja2 filters for transforming values:
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index f15356189..ea6adf995 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -202,25 +202,7 @@ Context JSON is piped to stdin for scripts that need structured data.
### Template variables
-All variables are shell-escaped:
-
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |
-| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |
-| `{{ repo }}` | Repository directory name (e.g., `myproject`) |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ worktree_name }}` | Worktree directory name |
-| `{{ worktree_path }}` | Absolute path to current worktree |
-| `{{ main_worktree_path }}` | Default branch worktree path |
-| `{{ commit }}` | Current HEAD commit SHA (full) |
-| `{{ short_commit }}` | Current HEAD commit SHA (7 chars) |
-| `{{ default_branch }}` | Default branch name (e.g., "main") |
-| `{{ remote }}` | Primary remote name (e.g., "origin") |
-| `{{ remote_url }}` | Primary remote URL |
-| `{{ upstream }}` | Upstream tracking branch, if configured |
-
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`).
+All variables are shell-escaped. See [`wt hook` template variables](https://worktrunk.dev/hook/#template-variables) for the complete list and filters.
### Examples
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 45977a0d5..87d5b1c53 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -20,17 +20,15 @@
# Named commands appear in output, making it easier to identify failures.
# ============================================================================
-# Template Variables
+# Template Variables — see https://worktrunk.dev/hook/#template-variables
# ============================================================================
-# All hooks support these variables:
+# Common variables:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
# {{ main_worktree_path }} - Absolute path to main worktree
# {{ default_branch }} - Default branch name (e.g., "main")
-#
-# Merge hooks (pre-commit, pre-merge, post-merge) also support:
-# {{ target }} - Target branch for the merge
+# {{ target }} - Target branch (merge hooks only)
#
# Filters:
# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
diff --git a/docs/content/config.md b/docs/content/config.md
index b21794bad..3a7765aab 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -533,17 +533,15 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# Named commands appear in output, making it easier to identify failures.
# ============================================================================
-# Template Variables
+# Template Variables — see https://worktrunk.dev/hook/#template-variables
# ============================================================================
-# All hooks support these variables:
+# Common variables:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
# {{ main_worktree_path }} - Absolute path to main worktree
# {{ default_branch }} - Default branch name (e.g., "main")
-#
-# Merge hooks (pre-commit, pre-merge, post-merge) also support:
-# {{ target }} - Target branch for the merge
+# {{ target }} - Target branch (merge hooks only)
#
# Filters:
# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 19ca55640..693f30f24 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -158,8 +158,6 @@ Hooks can use template variables that expand at runtime:
See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`). These still work but emit warnings.
-
### Filters
Templates support Jinja2 filters for transforming values:
diff --git a/docs/content/step.md b/docs/content/step.md
index d4581e125..7f1b35930 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -220,25 +220,7 @@ Context JSON is piped to stdin for scripts that need structured data.
### Template variables
-All variables are shell-escaped:
-
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |
-| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |
-| `{{ repo }}` | Repository directory name (e.g., `myproject`) |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ worktree_name }}` | Worktree directory name |
-| `{{ worktree_path }}` | Absolute path to current worktree |
-| `{{ main_worktree_path }}` | Default branch worktree path |
-| `{{ commit }}` | Current HEAD commit SHA (full) |
-| `{{ short_commit }}` | Current HEAD commit SHA (7 chars) |
-| `{{ default_branch }}` | Default branch name (e.g., "main") |
-| `{{ remote }}` | Primary remote name (e.g., "origin") |
-| `{{ remote_url }}` | Primary remote URL |
-| `{{ upstream }}` | Upstream tracking branch, if configured |
-
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`).
+All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
### Examples
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 1f607a8cd..4c7733d0b 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1150,8 +1150,6 @@ Hooks can use template variables that expand at runtime:
See [Designing effective hooks](#designing-effective-hooks) for `main_worktree_path` patterns.
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`). These still work but emit warnings.
-
### Filters
Templates support Jinja2 filters for transforming values:
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 3a4de803b..5ca9b7c85 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -172,25 +172,7 @@ Context JSON is piped to stdin for scripts that need structured data.
## Template variables
-All variables are shell-escaped:
-
-| Variable | Description |
-|----------|-------------|
-| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |
-| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |
-| `{{ repo }}` | Repository directory name (e.g., `myproject`) |
-| `{{ repo_path }}` | Absolute path to repository root |
-| `{{ worktree_name }}` | Worktree directory name |
-| `{{ worktree_path }}` | Absolute path to current worktree |
-| `{{ main_worktree_path }}` | Default branch worktree path |
-| `{{ commit }}` | Current HEAD commit SHA (full) |
-| `{{ short_commit }}` | Current HEAD commit SHA (7 chars) |
-| `{{ default_branch }}` | Default branch name (e.g., "main") |
-| `{{ remote }}` | Primary remote name (e.g., "origin") |
-| `{{ remote_url }}` | Primary remote URL |
-| `{{ upstream }}` | Upstream tracking branch, if configured |
-
-**Deprecated:** `repo_root` (use `repo_path`), `worktree` (use `worktree_path`), `main_worktree` (use `repo`).
+All variables are shell-escaped. See [`wt hook` template variables](@/hook.md#template-variables) for the complete list and filters.
## Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index a6974020c..030cc6ad6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -270,17 +270,15 @@ With --project, creates .config/wt.toml in the current repositor
# Named commands appear in output, making it easier to identify failures.

# ============================================================================
- # Template Variables
+ # Template Variables — see https://worktrunk.dev/hook/#template-variables
# ============================================================================
- # All hooks support these variables:
+ # Common variables:
# {{ repo }} - Repository directory name (e.g., "myproject")
# {{ branch }} - Branch name (e.g., "feature/auth")
# {{ worktree_path }} - Absolute path to worktree
# {{ main_worktree_path }} - Absolute path to main worktree
# {{ default_branch }} - Default branch name (e.g., "main")
- #
- # Merge hooks (pre-commit, pre-merge, post-merge) also support:
- # {{ target }} - Target branch for the merge
+ # {{ target }} - Target branch (merge hooks only)
#
# Filters:
# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")