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.mdindex 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.mdindex 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.mdindex 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.mdindex 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 FormattingUse gutter for **quoted content** (git output, commit messages, config to copy,diff --git a/dev/config.example.toml b/dev/config.example.tomlindex 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.tomlindex 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.mdindex 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 referencediff --git a/docs/content/hook.md b/docs/content/hook.mdindex 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.mdindex 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.rsindex 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.rsindex 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.rsindex 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 `-`////// # Examplesdiff --git a/src/llm.rs b/src/llm.rsindex 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 squasheddiff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snapindex 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: warnSOURCE_DATE_EPOCH: "1735776000"+ TERM: alacrittyWORKTRUNK_CONFIG_PATH: /nonexistent/test/config.tomlWORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"---@@ -115,7 +116,7 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[2m# Commands approved for project hooks in this repo[2m# Auto-populated when approving hooks (prompt on first run) or via `wt hook approvals add`[2m[projects."github.com/user/repo"]- [2mapproved-commands = ["npm install"]+ [2mapproved-commands = ["npm ci", "npm test"][2m[2m# NOTE: For project-specific hooks (post-create, post-start, pre-merge, etc.),[2m# use a separate PROJECT config file at <repo>/.config/wt.toml@@ -128,7 +129,7 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[2m# NOTE: Templates are synced from src/llm.rs by `cargo test readme_sync`[2m[2m# Optional: Custom prompt template (inline) - Uses minijinja syntax- [2m# Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}+ [2m# Available variables: {{ git_diff }}, {{ git_diff_stat }}, {{ branch }}, {{ recent_commits }}, {{ repo }}[2m# If not specified, uses the default template shown below:[2m# <!-- DEFAULT_TEMPLATE_START -->[2m# template = """@@ -242,121 +243,91 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[2m# Worktrunk Project Configuration[2m# Copy to: <repo>/.config/wt.toml[2m#- [2m# This file defines project-specific hooks that run automatically during- [2m# worktree operations. It should be checked into git and shared across all- [2m# developers working on the project.+ [2m# Project-specific hooks that run automatically during worktree operations.+ [2m# Check this file into git to share hooks across all developers.[2m- [2m# Available template variables (all hooks):- [2m# {{ repo }} - Repository name (e.g., "my-project")- [2m# {{ repo_path }} - Absolute path to repository (e.g., "/path/to/my-project")- [2m# {{ branch }} - Raw branch name (e.g., "feature/foo")- [2m# {{ worktree_path }} - Absolute path to worktree (e.g., "/path/to/my-project.feature-foo")+ [2m# ============================================================================+ [2m# Hook Formats+ [2m# ============================================================================+ [2m# All hooks support two formats:[2m#- [2m# Merge-related hooks also support:- [2m# {{ target }} - Target branch for the merge (e.g., "main" default branch)+ [2m# Single command:+ [2m# post-create = "npm install"[2m#- [2m# Filters:- [2m# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-foo")- [2m# {{ branch | hash_port }} - Hash string to deterministic port (10000-19999)+ [2m# Named table (multiple commands):+ [2m# [post-create]+ [2m# deps = "npm install"+ [2m# build = "npm run build"+ [2m#+ [2m# Named commands appear in output, making it easier to identify failures.[2m- [2m# Post-Create Hook- [2m# Runs SEQUENTIALLY and BLOCKS until complete- [2m# The worktree switch won't complete until these finish- [2m# Commands run one after another in the worktree directory+ [2m# ============================================================================+ [2m# Template Variables+ [2m# ============================================================================+ [2m# All hooks support these variables:+ [2m# {{ repo }} - Repository directory name (e.g., "myproject")+ [2m# {{ branch }} - Branch name (e.g., "feature/auth")+ [2m# {{ worktree_path }} - Absolute path to worktree+ [2m# {{ main_worktree_path }} - Absolute path to main worktree+ [2m# {{ default_branch }} - Default branch name (e.g., "main")[2m#- [2m# Format options:- [2m# 1. Single string:- [2m# post-create = "npm install"+ [2m# Merge hooks (pre-commit, pre-merge, post-merge) also support:+ [2m# {{ target }} - Target branch for the merge[2m#- [2m# 2. Named table (runs sequentially in declaration order):- [2m# [post-create]- [2m# install = "npm install --frozen-lockfile"- [2m# build = "npm run build"+ [2m# Filters:+ [2m# {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")+ [2m# {{ branch | hash_port }} - Deterministic port 10000-19999[2m- [2m# Post-Start Hook- [2m# Runs in BACKGROUND as detached processes (parallel)- [2m# Use for: uv sync, npm install, bundle install, build, dev servers, file watchers,- [2m# downloading assets too large for git (images, ML models, binaries), long-running tasks- [2m# The worktree switch completes immediately, these run in parallel- [2m# Output is logged to .git/wt-logs/{branch}-{source}-post-start-{name}.log (source: user/project)- [2m#- [2m# Format options:- [2m# 1. Single string:- [2m# post-start = "npm run dev"- [2m#- [2m# 2. Named table (runs in parallel):- [2m# [post-start]- [2m# server = "npm run dev"- [2m# watch = "npm run watch"+ [2m# ============================================================================+ [2m# Hooks+ [2m# ============================================================================[2m- [2m# Pre-Commit Hook- [2m# Runs SEQUENTIALLY before committing changes during merge (blocking, fail-fast)- [2m# All commands must exit with code 0 for commit to proceed- [2m# Runs for both squash and no-squash merge modes- [2m# Use for: formatters, linters, quick validation- [2m#- [2m# Single command:- [2m# pre-commit = "cargo fmt -- --check"+ [2m# Post-Create: Runs after worktree creation, BLOCKS until complete+ [2m# Use for: installing dependencies, setting up databases, copying configs[2m#- [2m# Multiple commands:- [2m# [pre-commit]- [2m# format = "cargo fmt -- --check"- [2m# lint = "cargo clippy -- -D warnings"+ [2m# [post-create]+ [2m# deps = "npm ci"+ [2m# env = "cp .env.example .env"[2m- [2m# Pre-Merge Hook- [2m# Runs SEQUENTIALLY before merging to target branch (blocking, fail-fast)- [2m# All commands must exit with code 0 for merge to proceed- [2m# Use for: tests, linters, build verification before merging- [2m#- [2m# Single command:- [2m# pre-merge = "cargo test"+ [2m# Post-Start: Runs in BACKGROUND after worktree creation (parallel)+ [2m# Use for: dev servers, file watchers, background builds+ [2m# Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log[2m#- [2m# Multiple commands:- [2m# [pre-merge]- [2m# test = "cargo test"- [2m# build = "cargo build --release"+ [2m# [post-start]+ [2m# server = "npm run dev -- --port {{ branch | hash_port }}"+ [2m# watch = "npm run watch"[2m- [2m# Post-Merge Hook- [2m# Runs SEQUENTIALLY in the worktree for the target branch if it exists, otherwise the main worktree (blocking)- [2m# Runs after push and cleanup complete- [2m# Use for: updating production builds, notifications, cleanup- [2m#- [2m# Single command:- [2m# post-merge = "cargo install --path ."+ [2m# Post-Switch: Runs in BACKGROUND after every switch (parallel)+ [2m# Use for: terminal tab naming, tmux window titles, IDE notifications[2m#- [2m# Multiple commands:- [2m# [post-merge]- [2m# install = "cargo install --path ."- [2m# notify = "echo 'Merged!'"+ [2m# post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"[2m- [2m# Example: Node.js Project- [2m# [post-create]- [2m# install = "npm ci"- [2m#- [2m# [post-start]- [2m# server = "npm run dev"+ [2m# Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)+ [2m# Use for: formatters, linters, quick checks[2m#- [2m# [pre-merge]+ [2m# [pre-commit]+ [2m# format = "npm run format:check"[2m# lint = "npm run lint"- [2m# test = "npm test"[2m- [2m# Example: Rust Project- [2m# [post-create]- [2m# build = "cargo build"+ [2m# Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)+ [2m# Use for: tests, build verification[2m#[2m# [pre-merge]- [2m# format = "cargo fmt -- --check"- [2m# clippy = "cargo clippy -- -D warnings"- [2m# test = "cargo test"+ [2m# test = "npm test"+ [2m# build = "npm run build"+ [2m+ [2m# Post-Merge: Runs after successful merge, BLOCKS+ [2m# Use for: deployment, notifications[2m#- [2m# post-merge = "cargo install --path ."+ [2m# post-merge = "echo 'Merged {{ branch }} to {{ target }}'"[2m- [2m# Example: Python Project- [2m# [post-create]- [2m# venv = "python -m venv .venv"- [2m# install = ".venv/bin/pip install -r requirements.txt"+ [2m# Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)+ [2m# Use for: cleanup, stopping services[2m#- [2m# [pre-merge]- [2m# format = ".venv/bin/black --check ."- [2m# lint = ".venv/bin/ruff check ."- [2m# test = ".venv/bin/pytest"+ [2m# pre-remove = "docker compose down"+ [2m+ [2m# ============================================================================+ [2m# Dev Server URL (shown in `wt list`)+ [2m# ============================================================================+ [2m# [list]+ [2m# 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.snapindex 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: warnSOURCE_DATE_EPOCH: "1735776000"+ TERM: alacrittyWORKTRUNK_CONFIG_PATH: /nonexistent/test/config.tomlWORKTRUNK_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.[1mAvailable variables:-- [2m{{ main_worktree }}[0m — main worktree directory name-- [2m{{ branch }}[0m — raw branch name (e.g., [2mfeature/foo[0m)+- [2m{{ repo }}[0m — repository directory name+- [2m{{ branch }}[0m — raw branch name (e.g., [2mfeature/auth[0m)- [2m{{ branch | sanitize }}[0m — branch name with [2m/[0m and [2m\[0m replaced by [2m-[1mExamples[0m for a repo at [2m~/code/myproject[0m creating branch [2mfeature/login[0m:[2m# Default — siblings in parent directory[2m# Creates: ~/code/myproject.feature-login- [2mworktree-path = "../{{ main_worktree }}.{{ branch | sanitize }}"+ [2mworktree-path = "../{{ repo }}.{{ branch | sanitize }}"[2m[2m# Inside the repository[2m# Creates: ~/code/myproject/.worktrees/feature-login@@ -95,7 +96,7 @@ Controls where new worktrees are created. The template is relative to the reposi[2m[2m# Namespaced (useful when multiple repos share a parent directory)[2m# Creates: ~/code/worktrees/myproject/feature-login- [2mworktree-path = "../worktrees/{{ main_worktree }}/{{ branch | sanitize }}"+ [2mworktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"[2m[2m# Nested bare repo (git clone --bare <url> project/.git)[2m# 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:[2m[projects."my-project"]- [2mapproved-commands = [- [2m "post-create.install = npm ci",- [2m "pre-merge.test = npm test",- [2m]+ [2mapproved-commands = ["npm ci", "npm test"]Manage approvals with [2mwt hook approvals add[0m to review and pre-approve commands, and [2mwt hook approvals clear[0m to reset (add [2m--global[0m to clear allprojects).