Skip to content

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

Improve default config examples (#432)

Maximilian Roosbd865a466fe7
diff --git a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md
index 3c20b2872..79fdc2fe1 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook-types-reference.md
@@ -14,7 +14,7 @@ Detailed behavior and use cases for all seven Worktrunk hook types.
| `post-merge` | After successful merge | Yes | No | Basic + Merge | Sequential |
| `pre-remove` | Before worktree removed | Yes | Yes | Basic | Sequential |
-**Basic variables**: `{{ repo }}`, `{{ repo_path }}`, `{{ branch }}`, `{{ worktree_name }}`, `{{ worktree_path }}`, `{{ default_branch }}`, `{{ commit }}`, `{{ short_commit }}`, `{{ remote }}`, `{{ remote_url }}`, `{{ upstream }}`
+**Basic variables**: `{{ repo }}`, `{{ repo_path }}`, `{{ branch }}`, `{{ worktree_name }}`, `{{ worktree_path }}`, `{{ main_worktree_path }}`, `{{ default_branch }}`, `{{ commit }}`, `{{ short_commit }}`, `{{ remote }}`, `{{ remote_url }}`, `{{ upstream }}`
**Merge variables**: Basic + `{{ target }}`
**Filters**: `{{ branch | sanitize }}` (replace `/` `\` with `-`), `{{ branch | hash_port }}` (port 10000-19999)
@@ -251,11 +251,12 @@ post-create = "echo 'Working on {{ branch }} in {{ repo }}'"
```
Available:
-- `{{ repo }}` - Repository name (e.g., "my-project")
-- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/my-project")
-- `{{ branch }}` - Branch name (e.g., "feature-auth")
-- `{{ worktree_name }}` - Worktree directory name (e.g., "my-project.feature-auth")
-- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/my-project.feature-auth")
+- `{{ repo }}` - Repository directory name (e.g., "myproject")
+- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/myproject")
+- `{{ branch }}` - Branch name (e.g., "feature/auth")
+- `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")
+- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/myproject.feature-auth")
+- `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")
- `{{ default_branch }}` - Default branch name (e.g., "main")
- `{{ commit }}` - Full HEAD commit SHA
- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)
diff --git a/.claude-plugin/skills/worktrunk/reference/project-config.md b/.claude-plugin/skills/worktrunk/reference/project-config.md
index 537368317..1a566543e 100644
--- a/.claude-plugin/skills/worktrunk/reference/project-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/project-config.md
@@ -187,11 +187,12 @@ All hooks support template variables for dynamic behavior.
### Basic Variables (All Hooks)
Available in all hook types:
-- `{{ repo }}` - Repository name (e.g., "my-project")
-- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/my-project")
+- `{{ repo }}` - Repository directory name (e.g., "myproject")
+- `{{ repo_path }}` - Absolute path to repository (e.g., "/path/to/myproject")
- `{{ branch }}` - Raw branch name (e.g., "feature/auth")
-- `{{ worktree_name }}` - Worktree directory name (e.g., "my-project.feature-auth")
-- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/my-project.feature-auth")
+- `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")
+- `{{ worktree_path }}` - Absolute path to worktree (e.g., "/path/to/myproject.feature-auth")
+- `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")
- `{{ default_branch }}` - Default branch name (e.g., "main")
- `{{ commit }}` - Full HEAD commit SHA
- `{{ short_commit }}` - Short HEAD commit SHA (7 chars)
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index 7bfac87ac..31c599818 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -107,7 +107,7 @@ Users may want different worktree organization patterns.
Default (parent siblings):
```toml
-worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
```
Result: `~/code/myproject` → `~/code/myproject.feature-auth`
@@ -129,12 +129,12 @@ Result: `~/code/myproject/.worktrees/feature-auth`
### Available Variables
-- `{{ main_worktree }}` - Main worktree directory name
-- `{{ branch }}` - Raw branch name (e.g., `feature/foo`)
+- `{{ repo }}` - Repository directory name
+- `{{ branch }}` - Raw branch name (e.g., `feature/auth`)
### Filters
-- `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., `feature-foo`)
+- `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., `feature-auth`)
- `{{ branch | hash_port }}` - Hash string to deterministic port (10000-19999)
### Validation Rules
@@ -178,13 +178,13 @@ template-file = "~/.config/worktrunk/commit-template.txt"
- `{{ git_diff }}` - Staged changes
- `{{ branch }}` - Current branch
- `{{ recent_commits }}` - Recent commit titles
-- `{{ repo }}` - Repository name
+- `{{ repo }}` - Repository directory name
**Squash commit templates**:
- `{{ commits }}` - List of commits being squashed
- `{{ target_branch }}` - Target branch for merge
- `{{ branch }}` - Current branch
-- `{{ repo }}` - Repository name
+- `{{ repo }}` - Repository directory name
### Validation Rules
@@ -205,7 +205,7 @@ Complete reference:
```toml
# Worktree Path Template
-worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# LLM Commit Generation (Optional)
[commit-generation]
diff --git a/.claude/rules/cli-output-formatting.md b/.claude/rules/cli-output-formatting.md
index a23beae38..0d99b138d 100644
--- a/.claude/rules/cli-output-formatting.md
+++ b/.claude/rules/cli-output-formatting.md
@@ -410,6 +410,51 @@ println!("{}", line.render());
See `src/commands/list/render.rs` for advanced usage.
+## Documentation Examples
+
+Use consistent examples throughout all documentation, help text, and config
+templates.
+
+### Canonical example setup
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Repo directory | `myproject` | Generic placeholder |
+| Repo path | `~/code/myproject` | Realistic dev path |
+| Branch | `feature/auth` | Shows sanitize filter |
+| Worktree path | `~/code/myproject.feature-auth` | Result of default template |
+
+### Template variable examples
+
+Use the canonical values from the table above in all examples:
+
+```
+{{ repo }} — Repository directory name (e.g., `myproject`)
+{{ branch }} — Branch name (e.g., `feature/auth`)
+{{ worktree_path }} — Absolute path to worktree (e.g., `/path/to/myproject.feature-auth`)
+```
+
+In TOML comments:
+```toml
+# {{ repo }} - Repository directory name (e.g., "myproject")
+# {{ branch }} - Raw branch name (e.g., "feature/auth")
+# {{ worktree_name }} - Worktree directory name (e.g., "myproject.feature-auth")
+```
+
+### Worktree path examples
+
+When showing worktree-path template examples:
+
+```toml
+# Default — siblings in parent directory
+# Creates: ~/code/myproject.feature-auth
+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+
+# Inside the repository
+# Creates: ~/code/myproject/.worktrees/feature-auth
+worktree-path = ".worktrees/{{ branch | sanitize }}"
+```
+
## Gutter Formatting
Use gutter for **quoted content** (git output, commit messages, config to copy,
diff --git a/dev/config.example.toml b/dev/config.example.toml
index bf33dd206..8584078df 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -68,7 +68,7 @@ verify = true # Run project hooks
# Commands approved for project hooks in this repo
# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`
[projects."github.com/user/repo"]
-approved-commands = ["npm install"]
+approved-commands = ["npm ci", "npm test"]
# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
@@ -81,7 +81,7 @@ approved-commands = ["npm install"]
# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`
# Optional: Custom prompt template (inline) - Uses minijinja syntax
-# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
+# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
# If not specified, uses the default template shown below:
# <!-- DEFAULT_TEMPLATE_START -->
# template = """
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 981df011e..06ac8fddc 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -1,121 +1,91 @@
# Worktrunk Project Configuration
# Copy to: <repo>/.config/wt.toml
#
-# This file defines project-specific hooks that run automatically during
-# worktree operations. It should be checked into git and shared across all
-# developers working on the project.
+# Project-specific hooks that run automatically during worktree operations.
+# Check this file into git to share hooks across all developers.
-# Available template variables (all hooks):
-# {{ repo }} - Repository name (e.g., "my-project")
-# {{ repo_path }} - Absolute path to repository (e.g., "/path/to/my-project")
-# {{ branch }} - Raw branch name (e.g., "feature/foo")
-# {{ worktree_path }} - Absolute path to worktree (e.g., "/path/to/my-project.feature-foo")
+# ============================================================================
+# Hook Formats
+# ============================================================================
+# All hooks support two formats:
#
-# Merge-related hooks also support:
-# {{ target }} - Target branch for the merge (e.g., "main" default branch)
+# Single command:
+# post-create = "npm install"
#
-# Filters:
-# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-foo")
-# {{ branch | hash_port }} - Hash string to deterministic port (10000-19999)
+# Named table (multiple commands):
+# [post-create]
+# deps = "npm install"
+# build = "npm run build"
+#
+# Named commands appear in output, making it easier to identify failures.
-# Post-Create Hook
-# Runs SEQUENTIALLY and BLOCKS until complete
-# The worktree switch won't complete until these finish
-# Commands run one after another in the worktree directory
+# ============================================================================
+# Template Variables
+# ============================================================================
+# All hooks support these 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
#
-# Format options:
-# 1. Single string:
-# post-create = "npm install"
+# Filters:
+# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
+# {{ branch | hash_port }} - Deterministic port 10000-19999
+
+# ============================================================================
+# Hooks
+# ============================================================================
+
+# Post-Create: Runs after worktree creation, BLOCKS until complete
+# Use for: installing dependencies, setting up databases, copying configs
#
-# 2. Named table (runs sequentially in declaration order):
# [post-create]
-# install = "npm install --frozen-lockfile"
-# build = "npm run build"
+# deps = "npm ci"
+# env = "cp .env.example .env"
-# Post-Start Hook
-# Runs in BACKGROUND as detached processes (parallel)
-# Use for: uv sync, npm install, bundle install, build, dev servers, file watchers,
-# downloading assets too large for git (images, ML models, binaries), long-running tasks
-# The worktree switch completes immediately, these run in parallel
-# Output is logged to .git/wt-logs/{branch}-{source}-post-start-{name}.log (source: user/project)
-#
-# Format options:
-# 1. Single string:
-# post-start = "npm run dev"
+# Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+# Use for: dev servers, file watchers, background builds
+# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
#
-# 2. Named table (runs in parallel):
# [post-start]
-# server = "npm run dev"
+# server = "npm run dev -- --port {{ branch | hash_port }}"
# watch = "npm run watch"
-# Pre-Commit Hook
-# Runs SEQUENTIALLY before committing changes during merge (blocking, fail-fast)
-# All commands must exit with code 0 for commit to proceed
-# Runs for both squash and no-squash merge modes
-# Use for: formatters, linters, quick validation
+# Post-Switch: Runs in BACKGROUND after every switch (parallel)
+# Use for: terminal tab naming, tmux window titles, IDE notifications
#
-# Single command:
-# pre-commit = "cargo fmt -- --check"
-#
-# Multiple commands:
-# [pre-commit]
-# format = "cargo fmt -- --check"
-# lint = "cargo clippy -- -D warnings"
-
-# Pre-Merge Hook
-# Runs SEQUENTIALLY before merging to target branch (blocking, fail-fast)
-# All commands must exit with code 0 for merge to proceed
-# Use for: tests, linters, build verification before merging
-#
-# Single command:
-# pre-merge = "cargo test"
-#
-# Multiple commands:
-# [pre-merge]
-# test = "cargo test"
-# build = "cargo build --release"
+# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
-# Post-Merge Hook
-# Runs SEQUENTIALLY in the worktree for the target branch if it exists, otherwise the main worktree (blocking)
-# Runs after push and cleanup complete
-# Use for: updating production builds, notifications, cleanup
+# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+# Use for: formatters, linters, quick checks
#
-# Single command:
-# post-merge = "cargo install --path ."
-#
-# Multiple commands:
-# [post-merge]
-# install = "cargo install --path ."
-# notify = "echo 'Merged!'"
+# [pre-commit]
+# format = "npm run format:check"
+# lint = "npm run lint"
-# Example: Node.js Project
-# [post-create]
-# install = "npm ci"
-#
-# [post-start]
-# server = "npm run dev"
+# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+# Use for: tests, build verification
#
# [pre-merge]
-# lint = "npm run lint"
# test = "npm test"
+# build = "npm run build"
-# Example: Rust Project
-# [post-create]
-# build = "cargo build"
-#
-# [pre-merge]
-# format = "cargo fmt -- --check"
-# clippy = "cargo clippy -- -D warnings"
-# test = "cargo test"
+# Post-Merge: Runs after successful merge, BLOCKS
+# Use for: deployment, notifications
#
-# post-merge = "cargo install --path ."
+# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
-# Example: Python Project
-# [post-create]
-# venv = "python -m venv .venv"
-# install = ".venv/bin/pip install -r requirements.txt"
+# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+# Use for: cleanup, stopping services
#
-# [pre-merge]
-# format = ".venv/bin/black --check ."
-# lint = ".venv/bin/ruff check ."
-# test = ".venv/bin/pytest"
+# pre-remove = "docker compose down"
+
+# ============================================================================
+# Dev Server URL (shown in `wt list`)
+# ============================================================================
+# [list]
+# url = "http://localhost:{{ branch | hash_port }}"
diff --git a/docs/content/config.md b/docs/content/config.md
index e383f4d81..17542cee4 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -52,8 +52,8 @@ The user config stores personal preferences that apply across all repositories.
Controls where new worktrees are created. The template is relative to the repository root.
**Available variables:**
-- `{{ main_worktree }}` — main worktree directory name
-- `{{ branch }}` — raw branch name (e.g., `feature/foo`)
+- `{{ repo }}` — repository directory name
+- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`
**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:
@@ -61,7 +61,7 @@ Controls where new worktrees are created. The template is relative to the reposi
```toml
# Default — siblings in parent directory
# Creates: ~/code/myproject.feature-login
-worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-login
@@ -69,7 +69,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"
# Namespaced (useful when multiple repos share a parent directory)
# Creates: ~/code/worktrees/myproject/feature-login
-worktree-path = "../worktrees/{{ main_worktree }}/{{ branch | sanitize }}"
+worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
# Nested bare repo (git clone --bare <url> project/.git)
# Creates: ~/code/project/feature-login (sibling to .git)
@@ -127,10 +127,7 @@ When project hooks run for the first time, Worktrunk prompts for approval. Appro
```toml
[projects."my-project"]
-approved-commands = [
- "post-create.install = npm ci",
- "pre-merge.test = npm test",
-]
+approved-commands = ["npm ci", "npm test"]
```
Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).
@@ -355,7 +352,7 @@ verify = true # Run project hooks
# Commands approved for project hooks in this repo
# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`
[projects."github.com/user/repo"]
-approved-commands = ["npm install"]
+approved-commands = ["npm ci", "npm test"]
# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
@@ -368,7 +365,7 @@ approved-commands = ["npm install"]
# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`
# Optional: Custom prompt template (inline) - Uses minijinja syntax
-# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
+# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
# If not specified, uses the default template shown below:
# <!-- DEFAULT_TEMPLATE_START -->
# template = """
@@ -484,124 +481,94 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# Worktrunk Project Configuration
# Copy to: <repo>/.config/wt.toml
#
-# This file defines project-specific hooks that run automatically during
-# worktree operations. It should be checked into git and shared across all
-# developers working on the project.
+# Project-specific hooks that run automatically during worktree operations.
+# Check this file into git to share hooks across all developers.
-# Available template variables (all hooks):
-# {{ repo }} - Repository name (e.g., "my-project")
-# {{ repo_path }} - Absolute path to repository (e.g., "/path/to/my-project")
-# {{ branch }} - Raw branch name (e.g., "feature/foo")
-# {{ worktree_path }} - Absolute path to worktree (e.g., "/path/to/my-project.feature-foo")
+# ============================================================================
+# Hook Formats
+# ============================================================================
+# All hooks support two formats:
#
-# Merge-related hooks also support:
-# {{ target }} - Target branch for the merge (e.g., "main" default branch)
+# Single command:
+# post-create = "npm install"
#
-# Filters:
-# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-foo")
-# {{ branch | hash_port }} - Hash string to deterministic port (10000-19999)
+# Named table (multiple commands):
+# [post-create]
+# deps = "npm install"
+# build = "npm run build"
+#
+# Named commands appear in output, making it easier to identify failures.
-# Post-Create Hook
-# Runs SEQUENTIALLY and BLOCKS until complete
-# The worktree switch won't complete until these finish
-# Commands run one after another in the worktree directory
+# ============================================================================
+# Template Variables
+# ============================================================================
+# All hooks support these 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")
#
-# Format options:
-# 1. Single string:
-# post-create = "npm install"
+# Merge hooks (pre-commit, pre-merge, post-merge) also support:
+# {{ target }} - Target branch for the merge
#
-# 2. Named table (runs sequentially in declaration order):
-# [post-create]
-# install = "npm install --frozen-lockfile"
-# build = "npm run build"
+# Filters:
+# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
+# {{ branch | hash_port }} - Deterministic port 10000-19999
-# Post-Start Hook
-# Runs in BACKGROUND as detached processes (parallel)
-# Use for: uv sync, npm install, bundle install, build, dev servers, file watchers,
-# downloading assets too large for git (images, ML models, binaries), long-running tasks
-# The worktree switch completes immediately, these run in parallel
-# Output is logged to .git/wt-logs/{branch}-{source}-post-start-{name}.log (source: user/project)
+# ============================================================================
+# Hooks
+# ============================================================================
+
+# Post-Create: Runs after worktree creation, BLOCKS until complete
+# Use for: installing dependencies, setting up databases, copying configs
#
-# Format options:
-# 1. Single string:
-# post-start = "npm run dev"
+# [post-create]
+# deps = "npm ci"
+# env = "cp .env.example .env"
+
+# Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+# Use for: dev servers, file watchers, background builds
+# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
#
-# 2. Named table (runs in parallel):
# [post-start]
-# server = "npm run dev"
+# server = "npm run dev -- --port {{ branch | hash_port }}"
# watch = "npm run watch"
-# Pre-Commit Hook
-# Runs SEQUENTIALLY before committing changes during merge (blocking, fail-fast)
-# All commands must exit with code 0 for commit to proceed
-# Runs for both squash and no-squash merge modes
-# Use for: formatters, linters, quick validation
+# Post-Switch: Runs in BACKGROUND after every switch (parallel)
+# Use for: terminal tab naming, tmux window titles, IDE notifications
#
-# Single command:
-# pre-commit = "cargo fmt -- --check"
-#
-# Multiple commands:
-# [pre-commit]
-# format = "cargo fmt -- --check"
-# lint = "cargo clippy -- -D warnings"
+# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
-# Pre-Merge Hook
-# Runs SEQUENTIALLY before merging to target branch (blocking, fail-fast)
-# All commands must exit with code 0 for merge to proceed
-# Use for: tests, linters, build verification before merging
-#
-# Single command:
-# pre-merge = "cargo test"
+# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+# Use for: formatters, linters, quick checks
#
-# Multiple commands:
-# [pre-merge]
-# test = "cargo test"
-# build = "cargo build --release"
-
-# Post-Merge Hook
-# Runs SEQUENTIALLY in the worktree for the target branch if it exists, otherwise the main worktree (blocking)
-# Runs after push and cleanup complete
-# Use for: updating production builds, notifications, cleanup
-#
-# Single command:
-# post-merge = "cargo install --path ."
-#
-# Multiple commands:
-# [post-merge]
-# install = "cargo install --path ."
-# notify = "echo 'Merged!'"
+# [pre-commit]
+# format = "npm run format:check"
+# lint = "npm run lint"
-# Example: Node.js Project
-# [post-create]
-# install = "npm ci"
-#
-# [post-start]
-# server = "npm run dev"
+# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+# Use for: tests, build verification
#
# [pre-merge]
-# lint = "npm run lint"
# test = "npm test"
+# build = "npm run build"
-# Example: Rust Project
-# [post-create]
-# build = "cargo build"
-#
-# [pre-merge]
-# format = "cargo fmt -- --check"
-# clippy = "cargo clippy -- -D warnings"
-# test = "cargo test"
+# Post-Merge: Runs after successful merge, BLOCKS
+# Use for: deployment, notifications
#
-# post-merge = "cargo install --path ."
+# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
-# Example: Python Project
-# [post-create]
-# venv = "python -m venv .venv"
-# install = ".venv/bin/pip install -r requirements.txt"
+# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+# Use for: cleanup, stopping services
#
-# [pre-merge]
-# format = ".venv/bin/black --check ."
-# lint = ".venv/bin/ruff check ."
-# test = ".venv/bin/pytest"
+# pre-remove = "docker compose down"
+
+# ============================================================================
+# Dev Server URL (shown in `wt list`)
+# ============================================================================
+# [list]
+# url = "http://localhost:{{ branch | hash_port }}"
```
### Command reference
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 3d5612edd..74a553e2b 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -140,12 +140,12 @@ Hooks can use template variables that expand at runtime:
| Variable | Example | Description |
|----------|---------|-------------|
-| `{{ repo }}` | my-project | Repository directory name |
-| `{{ repo_path }}` | /path/to/my-project | Absolute path to repository root |
-| `{{ branch }}` | feature-foo | Branch name |
-| `{{ worktree_name }}` | my-project.feature-foo | Worktree directory name |
-| `{{ worktree_path }}` | /path/to/my-project.feature-foo | Absolute worktree path |
-| `{{ main_worktree_path }}` | /path/to/my-project | Default branch worktree |
+| `{{ repo }}` | myproject | Repository directory name |
+| `{{ repo_path }}` | /path/to/myproject | Absolute path to repository root |
+| `{{ branch }}` | feature/auth | Branch name |
+| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |
+| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |
+| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |
| `{{ default_branch }}` | main | Default branch name |
| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |
| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |
diff --git a/docs/content/step.md b/docs/content/step.md
index 0c86748e0..bd67eeeab 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -82,9 +82,9 @@ All variables are shell-escaped:
| Variable | Description |
|----------|-------------|
-| `{{ branch }}` | Branch name (raw, e.g., `feature/foo`) |
+| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |
| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |
-| `{{ repo }}` | Repository directory name |
+| `{{ 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 |
diff --git a/src/cli.rs b/src/cli.rs
index 2fb0efb1f..9a342b3cc 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -951,9 +951,9 @@ All variables are shell-escaped:
| Variable | Description |
|----------|-------------|
-| `{{ branch }}` | Branch name (raw, e.g., `feature/foo`) |
+| `{{ branch }}` | Branch name (raw, e.g., `feature/auth`) |
| `{{ branch \| sanitize }}` | Branch name with `/` and `\` replaced by `-` |
-| `{{ repo }}` | Repository directory name |
+| `{{ 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 |
@@ -1230,8 +1230,8 @@ The user config stores personal preferences that apply across all repositories.
Controls where new worktrees are created. The template is relative to the repository root.
**Available variables:**
-- `{{ main_worktree }}` — main worktree directory name
-- `{{ branch }}` — raw branch name (e.g., `feature/foo`)
+- `{{ repo }}` — repository directory name
+- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — branch name with `/` and `\` replaced by `-`
**Examples** for a repo at `~/code/myproject` creating branch `feature/login`:
@@ -1239,7 +1239,7 @@ Controls where new worktrees are created. The template is relative to the reposi
```toml
# Default — siblings in parent directory
# Creates: ~/code/myproject.feature-login
-worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
+worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-login
@@ -1247,7 +1247,7 @@ worktree-path = ".worktrees/{{ branch | sanitize }}"
# Namespaced (useful when multiple repos share a parent directory)
# Creates: ~/code/worktrees/myproject/feature-login
-worktree-path = "../worktrees/{{ main_worktree }}/{{ branch | sanitize }}"
+worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
# Nested bare repo (git clone --bare <url> project/.git)
# Creates: ~/code/project/feature-login (sibling to .git)
@@ -1305,10 +1305,7 @@ When project hooks run for the first time, Worktrunk prompts for approval. Appro
```toml
[projects."my-project"]
-approved-commands = [
- "post-create.install = npm ci",
- "pre-merge.test = npm test",
-]
+approved-commands = ["npm ci", "npm test"]
```
Manage approvals with `wt hook approvals add` to review and pre-approve commands, and `wt hook approvals clear` to reset (add `--global` to clear all projects).
@@ -1619,12 +1616,12 @@ Hooks can use template variables that expand at runtime:
| Variable | Example | Description |
|----------|---------|-------------|
-| `{{ repo }}` | my-project | Repository directory name |
-| `{{ repo_path }}` | /path/to/my-project | Absolute path to repository root |
-| `{{ branch }}` | feature-foo | Branch name |
-| `{{ worktree_name }}` | my-project.feature-foo | Worktree directory name |
-| `{{ worktree_path }}` | /path/to/my-project.feature-foo | Absolute worktree path |
-| `{{ main_worktree_path }}` | /path/to/my-project | Default branch worktree |
+| `{{ repo }}` | myproject | Repository directory name |
+| `{{ repo_path }}` | /path/to/myproject | Absolute path to repository root |
+| `{{ branch }}` | feature/auth | Branch name |
+| `{{ worktree_name }}` | myproject.feature-auth | Worktree directory name |
+| `{{ worktree_path }}` | /path/to/myproject.feature-auth | Absolute worktree path |
+| `{{ main_worktree_path }}` | /path/to/myproject | Default branch worktree |
| `{{ default_branch }}` | main | Default branch name |
| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |
| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |
diff --git a/src/config/project.rs b/src/config/project.rs
index 653009183..cb17f51d9 100644
--- a/src/config/project.rs
+++ b/src/config/project.rs
@@ -48,12 +48,12 @@ impl ProjectListConfig {
/// # Template Variables
///
/// All hooks support these template variables:
-/// - `{{ repo }}` - Repository directory name (e.g., "my-project")
-/// - `{{ repo_path }}` - Absolute path to repository root
-/// - `{{ branch }}` - Branch name (e.g., "feature-foo")
-/// - `{{ worktree_name }}` - Worktree directory name (e.g., "my-project.feature-foo")
-/// - `{{ worktree_path }}` - Absolute path to the worktree
-/// - `{{ main_worktree_path }}` - Absolute path to the default branch worktree
+/// - `{{ repo }}` - Repository directory name (e.g., "myproject")
+/// - `{{ repo_path }}` - Absolute path to repository root (e.g., "/path/to/myproject")
+/// - `{{ branch }}` - Branch name (e.g., "feature/auth")
+/// - `{{ worktree_name }}` - Worktree directory name (e.g., "myproject.feature-auth")
+/// - `{{ worktree_path }}` - Absolute path to the worktree (e.g., "/path/to/myproject.feature-auth")
+/// - `{{ main_worktree_path }}` - Absolute path to main worktree (e.g., "/path/to/myproject")
/// - `{{ default_branch }}` - Default branch name (e.g., "main")
/// - `{{ commit }}` - Current HEAD commit SHA (full 40-character hash)
/// - `{{ short_commit }}` - Current HEAD commit SHA (short 7-character hash)
@@ -65,7 +65,7 @@ impl ProjectListConfig {
///
/// # Filters
///
-/// - `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., "feature-foo")
+/// - `{{ branch | sanitize }}` - Replace `/` and `\` with `-` (e.g., "feature-auth")
/// - `{{ branch | hash_port }}` - Hash string to deterministic port (10000-19999)
#[derive(Debug, Serialize, Deserialize, Clone, Default, PartialEq)]
pub struct ProjectConfig {
diff --git a/src/config/user.rs b/src/config/user.rs
index b566b9927..8dd58e633 100644
--- a/src/config/user.rs
+++ b/src/config/user.rs
@@ -91,8 +91,8 @@ pub enum StageMode {
///
/// The `worktree-path` template is relative to the repository root.
/// Supported variables:
-/// - `{{ repo }}` - Repository directory name
-/// - `{{ branch }}` - Raw branch name (e.g., `feature/foo`)
+/// - `{{ repo }}` - Repository directory name (e.g., `myproject`)
+/// - `{{ branch }}` - Raw branch name (e.g., `feature/auth`)
/// - `{{ branch | sanitize }}` - Branch name with `/` and `\` replaced by `-`
///
/// # Examples
diff --git a/src/llm.rs b/src/llm.rs
index fedfdd78e..862b01361 100644
--- a/src/llm.rs
+++ b/src/llm.rs
@@ -353,7 +353,7 @@ fn load_template(
/// - `git_diff`: The diff to describe
/// - `branch`: Current branch name
/// - `recent_commits`: Recent commit subjects for style reference
-/// - `repo`: Repository name
+/// - `repo`: Repository directory name
///
/// Squash-specific variables (empty for regular commits):
/// - `commits`: Commits being squashed
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 4eb231e47..641bd039b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -12,6 +12,7 @@ info:
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
@@ -115,7 +116,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# Commands approved for project hooks in this repo
# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`
[projects."github.com/user/repo"]
- approved-commands = ["npm install"]
+ approved-commands = ["npm ci", "npm test"]

# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),
# use a separate PROJECT config file at <repo>/.config/wt.toml
@@ -128,7 +129,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`

# Optional: Custom prompt template (inline) - Uses minijinja syntax
- # Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
+ # Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
# If not specified, uses the default template shown below:
# <!-- DEFAULT_TEMPLATE_START -->
# template = """
@@ -242,121 +243,91 @@ With --project, creates .config/wt.toml in the current repositor
# Worktrunk Project Configuration
# Copy to: <repo>/.config/wt.toml
#
- # This file defines project-specific hooks that run automatically during
- # worktree operations. It should be checked into git and shared across all
- # developers working on the project.
+ # Project-specific hooks that run automatically during worktree operations.
+ # Check this file into git to share hooks across all developers.

- # Available template variables (all hooks):
- # {{ repo }} - Repository name (e.g., "my-project")
- # {{ repo_path }} - Absolute path to repository (e.g., "/path/to/my-project")
- # {{ branch }} - Raw branch name (e.g., "feature/foo")
- # {{ worktree_path }} - Absolute path to worktree (e.g., "/path/to/my-project.feature-foo")
+ # ============================================================================
+ # Hook Formats
+ # ============================================================================
+ # All hooks support two formats:
#
- # Merge-related hooks also support:
- # {{ target }} - Target branch for the merge (e.g., "main" default branch)
+ # Single command:
+ # post-create = "npm install"
#
- # Filters:
- # {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-foo")
- # {{ branch | hash_port }} - Hash string to deterministic port (10000-19999)
+ # Named table (multiple commands):
+ # [post-create]
+ # deps = "npm install"
+ # build = "npm run build"
+ #
+ # Named commands appear in output, making it easier to identify failures.

- # Post-Create Hook
- # Runs SEQUENTIALLY and BLOCKS until complete
- # The worktree switch won't complete until these finish
- # Commands run one after another in the worktree directory
+ # ============================================================================
+ # Template Variables
+ # ============================================================================
+ # All hooks support these 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")
#
- # Format options:
- # 1. Single string:
- # post-create = "npm install"
+ # Merge hooks (pre-commit, pre-merge, post-merge) also support:
+ # {{ target }} - Target branch for the merge
#
- # 2. Named table (runs sequentially in declaration order):
- # [post-create]
- # install = "npm install --frozen-lockfile"
- # build = "npm run build"
+ # Filters:
+ # {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
+ # {{ branch | hash_port }} - Deterministic port 10000-19999

- # Post-Start Hook
- # Runs in BACKGROUND as detached processes (parallel)
- # Use for: uv sync, npm install, bundle install, build, dev servers, file watchers,
- # downloading assets too large for git (images, ML models, binaries), long-running tasks
- # The worktree switch completes immediately, these run in parallel
- # Output is logged to .git/wt-logs/{branch}-{source}-post-start-{name}.log (source: user/project)
- #
- # Format options:
- # 1. Single string:
- # post-start = "npm run dev"
- #
- # 2. Named table (runs in parallel):
- # [post-start]
- # server = "npm run dev"
- # watch = "npm run watch"
+ # ============================================================================
+ # Hooks
+ # ============================================================================

- # Pre-Commit Hook
- # Runs SEQUENTIALLY before committing changes during merge (blocking, fail-fast)
- # All commands must exit with code 0 for commit to proceed
- # Runs for both squash and no-squash merge modes
- # Use for: formatters, linters, quick validation
- #
- # Single command:
- # pre-commit = "cargo fmt -- --check"
+ # Post-Create: Runs after worktree creation, BLOCKS until complete
+ # Use for: installing dependencies, setting up databases, copying configs
#
- # Multiple commands:
- # [pre-commit]
- # format = "cargo fmt -- --check"
- # lint = "cargo clippy -- -D warnings"
+ # [post-create]
+ # deps = "npm ci"
+ # env = "cp .env.example .env"

- # Pre-Merge Hook
- # Runs SEQUENTIALLY before merging to target branch (blocking, fail-fast)
- # All commands must exit with code 0 for merge to proceed
- # Use for: tests, linters, build verification before merging
- #
- # Single command:
- # pre-merge = "cargo test"
+ # Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+ # Use for: dev servers, file watchers, background builds
+ # Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
#
- # Multiple commands:
- # [pre-merge]
- # test = "cargo test"
- # build = "cargo build --release"
+ # [post-start]
+ # server = "npm run dev -- --port {{ branch | hash_port }}"
+ # watch = "npm run watch"

- # Post-Merge Hook
- # Runs SEQUENTIALLY in the worktree for the target branch if it exists, otherwise the main worktree (blocking)
- # Runs after push and cleanup complete
- # Use for: updating production builds, notifications, cleanup
- #
- # Single command:
- # post-merge = "cargo install --path ."
+ # Post-Switch: Runs in BACKGROUND after every switch (parallel)
+ # Use for: terminal tab naming, tmux window titles, IDE notifications
#
- # Multiple commands:
- # [post-merge]
- # install = "cargo install --path ."
- # notify = "echo 'Merged!'"
+ # post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"

- # Example: Node.js Project
- # [post-create]
- # install = "npm ci"
- #
- # [post-start]
- # server = "npm run dev"
+ # Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+ # Use for: formatters, linters, quick checks
#
- # [pre-merge]
+ # [pre-commit]
+ # format = "npm run format:check"
# lint = "npm run lint"
- # test = "npm test"

- # Example: Rust Project
- # [post-create]
- # build = "cargo build"
+ # Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+ # Use for: tests, build verification
#
# [pre-merge]
- # format = "cargo fmt -- --check"
- # clippy = "cargo clippy -- -D warnings"
- # test = "cargo test"
+ # test = "npm test"
+ # build = "npm run build"
+ 
+ # Post-Merge: Runs after successful merge, BLOCKS
+ # Use for: deployment, notifications
#
- # post-merge = "cargo install --path ."
+ # post-merge = "echo 'Merged {{ branch }} to {{ target }}'"

- # Example: Python Project
- # [post-create]
- # venv = "python -m venv .venv"
- # install = ".venv/bin/pip install -r requirements.txt"
+ # Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+ # Use for: cleanup, stopping services
#
- # [pre-merge]
- # format = ".venv/bin/black --check ."
- # lint = ".venv/bin/ruff check ."
- # test = ".venv/bin/pytest"
+ # pre-remove = "docker compose down"
+ 
+ # ============================================================================
+ # Dev Server URL (shown in `wt list`)
+ # ============================================================================
+ # [list]
+ # url = "http://localhost:{{ branch | hash_port }}"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index dee6d64d3..d1421f488 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -11,6 +11,7 @@ info:
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
@@ -79,15 +80,15 @@ The user config stores personal preferences that apply across all repositories.
Controls where new worktrees are created. The template is relative to the repository root.
Available variables:
-- {{ main_worktree }} — main worktree directory name
-- {{ branch }} — raw branch name (e.g., feature/foo)
+- {{ repo }} — repository directory name
+- {{ branch }} — raw branch name (e.g., feature/auth)
- {{ branch | sanitize }} — branch name with / and \ replaced by -
Examples for a repo at ~/code/myproject creating branch feature/login:
# Default — siblings in parent directory
# Creates: ~/code/myproject.feature-login
- worktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"
+ worktree-path = "../{{ repo }}.{{ branch | sanitize }}"

# Inside the repository
# Creates: ~/code/myproject/.worktrees/feature-login
@@ -95,7 +96,7 @@ Controls where new worktrees are created. The template is relative to the reposi

# Namespaced (useful when multiple repos share a parent directory)
# Creates: ~/code/worktrees/myproject/feature-login
- worktree-path = "../worktrees/{{ main_worktree }}/{{ branch | sanitize }}"
+ worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"

# Nested bare repo (git clone --bare <url> project/.git)
# Creates: ~/code/project/feature-login (sibling to .git)
@@ -143,10 +144,7 @@ See LLM Commit Messages for setup details and template customization.
When project hooks run for the first time, Worktrunk prompts for approval. Approved commands are saved here automatically:
[projects."my-project"]
- approved-commands = [
-  "post-create.install = npm ci",
-  "pre-merge.test = npm test",
- ]
+ approved-commands = ["npm ci", "npm test"]
Manage approvals with wt hook approvals add to review and pre-approve commands, and wt hook approvals clear to reset (add --global to clear all
projects).