Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(hook): reorganize and trim help for clarity (#619)
Maximilian Roosa6ee0481208d
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.mdindex 6947c7eb5..b2597f937 100644--- a/.claude-plugin/skills/worktrunk/reference/hook.md+++ b/.claude-plugin/skills/worktrunk/reference/hook.md@@ -21,9 +21,7 @@ Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook### post-create-Runs after worktree creation, **blocks until complete**. The worktree switch doesn't finish until these commands succeed.--**Use cases**: Installing dependencies, database migrations, copying environment files.+Installing dependencies, database migrations, copying environment files.```toml[post-create]@@ -34,9 +32,7 @@ env = "cp .env.example .env"### post-start-Runs after worktree creation, **in background**. The worktree switch completes immediately; these run in parallel.--**Use cases**: Long builds, dev servers, file watchers, downloading large assets.+Long builds, dev servers, file watchers, downloading large assets. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml[post-start]@@ -44,25 +40,17 @@ build = "npm run build"server = "npm run dev"```-Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log` (source is `user` or `project`).-### post-switch-Runs after **every** switch operation, **in background**. Triggers on all switch results: creating new worktrees, switching to existing ones, or switching to the current worktree.--**Use cases**: Renaming terminal tabs, updating tmux window names, IDE notifications.+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Useful for terminal tab renaming, tmux window names, IDE notifications. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.```tomlpost-switch = "echo 'Switched to {{ branch }}'"```-Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log` (source is `user` or `project`).-### pre-commit-Runs before committing during `wt merge`, **fail-fast**. All commands must exit 0 for the commit to proceed.--**Use cases**: Formatters, linters, type checking.+Formatters, linters, type checking — runs during `wt merge` before the squash commit.```toml[pre-commit]@@ -72,9 +60,7 @@ lint = "cargo clippy -- -D warnings"### pre-merge-Runs before merging to target branch, **fail-fast**. All commands must exit 0 for the merge to proceed.--**Use cases**: Tests, security scans, build verification.+Tests, security scans, build verification — runs after rebase, before merge to target.```toml[pre-merge]@@ -84,9 +70,7 @@ build = "cargo build --release"### post-merge-Runs after successful merge in the **worktree for the target branch** if it exists, otherwise the **main worktree**, **best-effort**. Failures are logged but don't abort.--**Use cases**: Deployment, notifications, installing updated binaries.+Deployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.```tomlpost-merge = "cargo install --path ."@@ -94,23 +78,34 @@ post-merge = "cargo install --path ."### pre-remove-Runs before worktree removal during `wt remove`, **fail-fast**. All commands must exit 0 for removal to proceed.--**Use cases**: Cleanup tasks, saving state, notifying external systems.+Cleanup tasks, saving state, notifying external systems.```toml[pre-remove]cleanup = "rm -rf /tmp/cache/{{ branch }}"```-### Timing during merge+During `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-merge. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.++## Security++Project commands require approval on first run:++```+▲ repo needs approval to execute 3 commands:++○ post-create install:+ echo 'Installing dependencies...'-- **pre-commit** — After staging, before squash commit-- **pre-merge** — After rebase, before merge to target-- **pre-remove** — Before removing worktree during cleanup-- **post-merge** — After cleanup completes+❯ Allow and remember? [y/N]+```++- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)+- If a command changes, new approval is required+- Use `--yes` to bypass prompts (useful for CI/automation)+- Use `--no-verify` to skip hooks-See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.+Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.## Configuration@@ -126,27 +121,76 @@ test = "cargo test"build = "cargo build --release"```+### User hooks++Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.++```toml+# ~/.config/worktrunk/config.toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks support the same hook types and template variables as project hooks.++**Key differences from project hooks:**++| Aspect | Project hooks | User hooks |+|--------|--------------|------------|+| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |+| Scope | Single repository | All repositories |+| Approval | Required | Not required |+| Execution order | After user hooks | Before project hooks |++Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.++**Use cases:**+- Personal notifications or logging+- Editor/IDE integration+- Repository-agnostic setup tasks+- Filtering by repository using JSON context++**Filtering by repository:**++User hooks receive JSON context on stdin, enabling repository-specific behavior:++```toml+# ~/.config/worktrunk/config.toml+[post-create]+gitlab-setup = """+python3 -c '+import json, sys, subprocess+ctx = json.load(sys.stdin)+if "gitlab" in ctx.get("remote", ""):+ subprocess.run(["glab", "mr", "create", "--fill"])+'+"""+```+### Template variablesHooks can use template variables that expand at runtime:-| Variable | Example | Description |-|----------|---------|-------------|-| `{{ 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 |-| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |-| `{{ default_branch }}` | main | Default branch name |-| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |-| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |-| `{{ remote }}` | origin | Primary remote name |-| `{{ remote_url }}` | [email protected]:user/repo.git | Remote URL |-| `{{ upstream }}` | origin/feature | Upstream tracking branch |-| `{{ target }}` | main | Target branch (merge hooks only) |-| `{{ base }}` | main | Base branch (creation hooks only) |-| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |+| Variable | Description |+|----------|-------------|+| `{{ repo }}` | Repository directory name |+| `{{ repo_path }}` | Absolute path to repository root |+| `{{ branch }}` | Branch name |+| `{{ worktree_name }}` | Worktree directory name |+| `{{ worktree_path }}` | Absolute worktree path |+| `{{ primary_worktree_path }}` | Main worktree path (for bare repos: default branch worktree) |+| `{{ default_branch }}` | Default branch name |+| `{{ commit }}` | Full HEAD commit SHA |+| `{{ short_commit }}` | Short HEAD commit SHA (7 chars) |+| `{{ remote }}` | Primary remote name |+| `{{ remote_url }}` | Remote URL |+| `{{ upstream }}` | Upstream tracking branch |+| `{{ target }}` | Target branch (merge hooks only) |+| `{{ base }}` | Base branch (creation hooks only) |+| `{{ base_worktree_path }}` | Base branch worktree (creation hooks only) |### Worktrunk Filters@@ -200,6 +244,25 @@ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")The JSON includes all template variables plus `hook_type` and `hook_name`.+## Running hooks manually++`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.++```bash+wt hook pre-merge # Run all pre-merge hooks+wt hook pre-merge test # Run hooks named "test" from both sources+wt hook pre-merge user: # Run all user hooks+wt hook pre-merge project: # Run all project hooks+wt hook pre-merge user:test # Run only user's "test" hook+wt hook pre-merge project:test # Run only project's "test" hook+wt hook pre-merge --yes # Skip approval prompts (for CI)+wt hook post-create --var branch=feature/test # Override template variable+```++The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.++The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.+## Designing effective hooks### post-create vs post-start@@ -281,117 +344,9 @@ EOF"""```-## Security--Project commands require approval on first run:--```-▲ repo needs approval to execute 3 commands:+### Progressive validation-○ post-create install:- echo 'Installing dependencies...'--❯ Allow and remember? [y/N]-```--- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)-- If a command changes, new approval is required-- Use `--yes` to bypass prompts (useful for CI/automation)-- Use `--no-verify` to skip hooks--Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.--## User hooks--Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.--```toml-# ~/.config/worktrunk/config.toml-[post-create]-setup = "echo 'Setting up worktree...'"--[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"-```--User hooks support the same hook types and template variables as project hooks.--**Key differences from project hooks:**--| Aspect | Project hooks | User hooks |-|--------|--------------|------------|-| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |-| Scope | Single repository | All repositories |-| Approval | Required | Not required |-| Execution order | After user hooks | Before project hooks |--Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.--**Use cases:**-- Personal notifications or logging-- Editor/IDE integration-- Repository-agnostic setup tasks-- Filtering by repository using JSON context--**Filtering by repository:**--User hooks receive JSON context on stdin, enabling repository-specific behavior:--```toml-# ~/.config/worktrunk/config.toml-[post-create]-gitlab-setup = """-python3 -c '-import json, sys, subprocess-ctx = json.load(sys.stdin)-if "gitlab" in ctx.get("remote", ""):- subprocess.run(["glab", "mr", "create", "--fill"])-'-"""-```--## Running hooks manually--`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.--```bash-wt hook pre-merge # Run all pre-merge hooks-wt hook pre-merge test # Run hooks named "test" from both sources-wt hook pre-merge user: # Run all user hooks-wt hook pre-merge project: # Run all project hooks-wt hook pre-merge user:test # Run only user's "test" hook-wt hook pre-merge project:test # Run only project's "test" hook-wt hook pre-merge --yes # Skip approval prompts (for CI)-wt hook post-create --var branch=feature/test # Override template variable-```--The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.--The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.--## Language-specific tips--Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](https://worktrunk.dev/step/#language-specific-notes). This section covers hooks.--### Python--Use `uv sync` to recreate virtual environments:--```toml-[post-create]-install = "uv sync"-```--For pip-based projects without uv:--```toml-[post-create]-venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"-```--### Hook flow patterns--**Progressive validation** — Quick checks before commit, thorough validation before merge:+Quick checks before commit, thorough validation before merge:```toml[pre-commit]@@ -403,7 +358,9 @@ test = "npm test"build = "npm run build"```-**Target-specific behavior** — Different actions for production vs staging:+### Target-specific behavior++Different actions for production vs staging:```tomlpost-merge = """@@ -415,6 +372,17 @@ fi"""```+### Python virtual environments++Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):++```toml+[post-create]+install = "uv sync"+```++For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](https://worktrunk.dev/step/#language-specific-notes).+## Command referencewt hook - Run configured hooksdiff --git a/docs/content/hook.md b/docs/content/hook.mdindex 68f3c6d01..f98268c8c 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -29,9 +29,7 @@ Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook### post-create-Runs after worktree creation, **blocks until complete**. The worktree switch doesn't finish until these commands succeed.--**Use cases**: Installing dependencies, database migrations, copying environment files.+Installing dependencies, database migrations, copying environment files.```toml[post-create]@@ -42,9 +40,7 @@ env = "cp .env.example .env"### post-start-Runs after worktree creation, **in background**. The worktree switch completes immediately; these run in parallel.--**Use cases**: Long builds, dev servers, file watchers, downloading large assets.+Long builds, dev servers, file watchers, downloading large assets. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml[post-start]@@ -52,25 +48,17 @@ build = "npm run build"server = "npm run dev"```-Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log` (source is `user` or `project`).-### post-switch-Runs after **every** switch operation, **in background**. Triggers on all switch results: creating new worktrees, switching to existing ones, or switching to the current worktree.--**Use cases**: Renaming terminal tabs, updating tmux window names, IDE notifications.+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Useful for terminal tab renaming, tmux window names, IDE notifications. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.```tomlpost-switch = "echo 'Switched to {{ branch }}'"```-Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log` (source is `user` or `project`).-### pre-commit-Runs before committing during `wt merge`, **fail-fast**. All commands must exit 0 for the commit to proceed.--**Use cases**: Formatters, linters, type checking.+Formatters, linters, type checking — runs during `wt merge` before the squash commit.```toml[pre-commit]@@ -80,9 +68,7 @@ lint = "cargo clippy -- -D warnings"### pre-merge-Runs before merging to target branch, **fail-fast**. All commands must exit 0 for the merge to proceed.--**Use cases**: Tests, security scans, build verification.+Tests, security scans, build verification — runs after rebase, before merge to target.```toml[pre-merge]@@ -92,9 +78,7 @@ build = "cargo build --release"### post-merge-Runs after successful merge in the **worktree for the target branch** if it exists, otherwise the **main worktree**, **best-effort**. Failures are logged but don't abort.--**Use cases**: Deployment, notifications, installing updated binaries.+Deployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.```tomlpost-merge = "cargo install --path ."@@ -102,23 +86,34 @@ post-merge = "cargo install --path ."### pre-remove-Runs before worktree removal during `wt remove`, **fail-fast**. All commands must exit 0 for removal to proceed.--**Use cases**: Cleanup tasks, saving state, notifying external systems.+Cleanup tasks, saving state, notifying external systems.```toml[pre-remove]cleanup = "rm -rf /tmp/cache/{{ branch }}"```-### Timing during merge+During `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.++## Security++Project commands require approval on first run:++```+▲ repo needs approval to execute 3 commands:++○ post-create install:+ echo 'Installing dependencies...'-- **pre-commit** — After staging, before squash commit-- **pre-merge** — After rebase, before merge to target-- **pre-remove** — Before removing worktree during cleanup-- **post-merge** — After cleanup completes+❯ Allow and remember? [y/N]+```++- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)+- If a command changes, new approval is required+- Use `--yes` to bypass prompts (useful for CI/automation)+- Use `--no-verify` to skip hooks-See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.+Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.## Configuration@@ -134,27 +129,76 @@ test = "cargo test"build = "cargo build --release"```+### User hooks++Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.++```toml+# ~/.config/worktrunk/config.toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks support the same hook types and template variables as project hooks.++**Key differences from project hooks:**++| Aspect | Project hooks | User hooks |+|--------|--------------|------------|+| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |+| Scope | Single repository | All repositories |+| Approval | Required | Not required |+| Execution order | After user hooks | Before project hooks |++Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.++**Use cases:**+- Personal notifications or logging+- Editor/IDE integration+- Repository-agnostic setup tasks+- Filtering by repository using JSON context++**Filtering by repository:**++User hooks receive JSON context on stdin, enabling repository-specific behavior:++```toml+# ~/.config/worktrunk/config.toml+[post-create]+gitlab-setup = """+python3 -c '+import json, sys, subprocess+ctx = json.load(sys.stdin)+if "gitlab" in ctx.get("remote", ""):+ subprocess.run(["glab", "mr", "create", "--fill"])+'+"""+```+### Template variablesHooks can use template variables that expand at runtime:-| Variable | Example | Description |-|----------|---------|-------------|-| `{{ 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 |-| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |-| `{{ default_branch }}` | main | Default branch name |-| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |-| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |-| `{{ remote }}` | origin | Primary remote name |-| `{{ remote_url }}` | [email protected]:user/repo.git | Remote URL |-| `{{ upstream }}` | origin/feature | Upstream tracking branch |-| `{{ target }}` | main | Target branch (merge hooks only) |-| `{{ base }}` | main | Base branch (creation hooks only) |-| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |+| Variable | Description |+|----------|-------------|+| `{{ repo }}` | Repository directory name |+| `{{ repo_path }}` | Absolute path to repository root |+| `{{ branch }}` | Branch name |+| `{{ worktree_name }}` | Worktree directory name |+| `{{ worktree_path }}` | Absolute worktree path |+| `{{ primary_worktree_path }}` | Main worktree path (for bare repos: default branch worktree) |+| `{{ default_branch }}` | Default branch name |+| `{{ commit }}` | Full HEAD commit SHA |+| `{{ short_commit }}` | Short HEAD commit SHA (7 chars) |+| `{{ remote }}` | Primary remote name |+| `{{ remote_url }}` | Remote URL |+| `{{ upstream }}` | Upstream tracking branch |+| `{{ target }}` | Target branch (merge hooks only) |+| `{{ base }}` | Base branch (creation hooks only) |+| `{{ base_worktree_path }}` | Base branch worktree (creation hooks only) |### Worktrunk Filters@@ -208,6 +252,25 @@ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")The JSON includes all template variables plus `hook_type` and `hook_name`.+## Running hooks manually++`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.++```bash+wt hook pre-merge # Run all pre-merge hooks+wt hook pre-merge test # Run hooks named "test" from both sources+wt hook pre-merge user: # Run all user hooks+wt hook pre-merge project: # Run all project hooks+wt hook pre-merge user:test # Run only user's "test" hook+wt hook pre-merge project:test # Run only project's "test" hook+wt hook pre-merge --yes # Skip approval prompts (for CI)+wt hook post-create --var branch=feature/test # Override template variable+```++The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.++The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.+## Designing effective hooks### post-create vs post-start@@ -289,117 +352,9 @@ EOF"""```-## Security--Project commands require approval on first run:--```-▲ repo needs approval to execute 3 commands:+### Progressive validation-○ post-create install:- echo 'Installing dependencies...'--❯ Allow and remember? [y/N]-```--- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)-- If a command changes, new approval is required-- Use `--yes` to bypass prompts (useful for CI/automation)-- Use `--no-verify` to skip hooks--Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.--## User hooks--Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.--```toml-# ~/.config/worktrunk/config.toml-[post-create]-setup = "echo 'Setting up worktree...'"--[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"-```--User hooks support the same hook types and template variables as project hooks.--**Key differences from project hooks:**--| Aspect | Project hooks | User hooks |-|--------|--------------|------------|-| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |-| Scope | Single repository | All repositories |-| Approval | Required | Not required |-| Execution order | After user hooks | Before project hooks |--Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.--**Use cases:**-- Personal notifications or logging-- Editor/IDE integration-- Repository-agnostic setup tasks-- Filtering by repository using JSON context--**Filtering by repository:**--User hooks receive JSON context on stdin, enabling repository-specific behavior:--```toml-# ~/.config/worktrunk/config.toml-[post-create]-gitlab-setup = """-python3 -c '-import json, sys, subprocess-ctx = json.load(sys.stdin)-if "gitlab" in ctx.get("remote", ""):- subprocess.run(["glab", "mr", "create", "--fill"])-'-"""-```--## Running hooks manually--`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.--```bash-wt hook pre-merge # Run all pre-merge hooks-wt hook pre-merge test # Run hooks named "test" from both sources-wt hook pre-merge user: # Run all user hooks-wt hook pre-merge project: # Run all project hooks-wt hook pre-merge user:test # Run only user's "test" hook-wt hook pre-merge project:test # Run only project's "test" hook-wt hook pre-merge --yes # Skip approval prompts (for CI)-wt hook post-create --var branch=feature/test # Override template variable-```--The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.--The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.--## Language-specific tips--Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes). This section covers hooks.--### Python--Use `uv sync` to recreate virtual environments:--```toml-[post-create]-install = "uv sync"-```--For pip-based projects without uv:--```toml-[post-create]-venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"-```--### Hook flow patterns--**Progressive validation** — Quick checks before commit, thorough validation before merge:+Quick checks before commit, thorough validation before merge:```toml[pre-commit]@@ -411,7 +366,9 @@ test = "npm test"build = "npm run build"```-**Target-specific behavior** — Different actions for production vs staging:+### Target-specific behavior++Different actions for production vs staging:```tomlpost-merge = """@@ -423,6 +380,17 @@ fi"""```+### Python virtual environments++Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):++```toml+[post-create]+install = "uv sync"+```++For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes).+## See also- [`wt merge`](@/merge.md) — Runs hooks automatically during mergediff --git a/src/cli/mod.rs b/src/cli/mod.rsindex fab265413..5b728d891 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1057,9 +1057,7 @@ Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook### post-create-Runs after worktree creation, **blocks until complete**. The worktree switch doesn't finish until these commands succeed.--**Use cases**: Installing dependencies, database migrations, copying environment files.+Installing dependencies, database migrations, copying environment files.```toml[post-create]@@ -1070,9 +1068,7 @@ env = "cp .env.example .env"### post-start-Runs after worktree creation, **in background**. The worktree switch completes immediately; these run in parallel.--**Use cases**: Long builds, dev servers, file watchers, downloading large assets.+Long builds, dev servers, file watchers, downloading large assets. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml[post-start]@@ -1080,25 +1076,17 @@ build = "npm run build"server = "npm run dev"```-Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log` (source is `user` or `project`).-### post-switch-Runs after **every** switch operation, **in background**. Triggers on all switch results: creating new worktrees, switching to existing ones, or switching to the current worktree.--**Use cases**: Renaming terminal tabs, updating tmux window names, IDE notifications.+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Useful for terminal tab renaming, tmux window names, IDE notifications. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.```tomlpost-switch = "echo 'Switched to {{ branch }}'"```-Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log` (source is `user` or `project`).-### pre-commit-Runs before committing during `wt merge`, **fail-fast**. All commands must exit 0 for the commit to proceed.--**Use cases**: Formatters, linters, type checking.+Formatters, linters, type checking — runs during `wt merge` before the squash commit.```toml[pre-commit]@@ -1108,9 +1096,7 @@ lint = "cargo clippy -- -D warnings"### pre-merge-Runs before merging to target branch, **fail-fast**. All commands must exit 0 for the merge to proceed.--**Use cases**: Tests, security scans, build verification.+Tests, security scans, build verification — runs after rebase, before merge to target.```toml[pre-merge]@@ -1120,9 +1106,7 @@ build = "cargo build --release"### post-merge-Runs after successful merge in the **worktree for the target branch** if it exists, otherwise the **main worktree**, **best-effort**. Failures are logged but don't abort.--**Use cases**: Deployment, notifications, installing updated binaries.+Deployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.```tomlpost-merge = "cargo install --path ."@@ -1130,23 +1114,34 @@ post-merge = "cargo install --path ."### pre-remove-Runs before worktree removal during `wt remove`, **fail-fast**. All commands must exit 0 for removal to proceed.--**Use cases**: Cleanup tasks, saving state, notifying external systems.+Cleanup tasks, saving state, notifying external systems.```toml[pre-remove]cleanup = "rm -rf /tmp/cache/{{ branch }}"```-### Timing during merge+During `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.++## Security++Project commands require approval on first run:++```+▲ repo needs approval to execute 3 commands:++○ post-create install:+ echo 'Installing dependencies...'-- **pre-commit** — After staging, before squash commit-- **pre-merge** — After rebase, before merge to target-- **pre-remove** — Before removing worktree during cleanup-- **post-merge** — After cleanup completes+❯ Allow and remember? [y/N]+```++- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)+- If a command changes, new approval is required+- Use `--yes` to bypass prompts (useful for CI/automation)+- Use `--no-verify` to skip hooks-See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.+Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.## Configuration@@ -1162,27 +1157,76 @@ test = "cargo test"build = "cargo build --release"```+### User hooks++Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.++```toml+# ~/.config/worktrunk/config.toml+[post-create]+setup = "echo 'Setting up worktree...'"++[pre-merge]+notify = "notify-send 'Merging {{ branch }}'"+```++User hooks support the same hook types and template variables as project hooks.++**Key differences from project hooks:**++| Aspect | Project hooks | User hooks |+|--------|--------------|------------|+| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |+| Scope | Single repository | All repositories |+| Approval | Required | Not required |+| Execution order | After user hooks | Before project hooks |++Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.++**Use cases:**+- Personal notifications or logging+- Editor/IDE integration+- Repository-agnostic setup tasks+- Filtering by repository using JSON context++**Filtering by repository:**++User hooks receive JSON context on stdin, enabling repository-specific behavior:++```toml+# ~/.config/worktrunk/config.toml+[post-create]+gitlab-setup = """+python3 -c '+import json, sys, subprocess+ctx = json.load(sys.stdin)+if "gitlab" in ctx.get("remote", ""):+ subprocess.run(["glab", "mr", "create", "--fill"])+'+"""+```+### Template variablesHooks can use template variables that expand at runtime:-| Variable | Example | Description |-|----------|---------|-------------|-| `{{ 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 |-| `{{ primary_worktree_path }}` | /path/to/myproject | Main worktree path (or for bare repos, the default branch worktree) |-| `{{ default_branch }}` | main | Default branch name |-| `{{ commit }}` | a1b2c3d4e5f6... | Full HEAD commit SHA |-| `{{ short_commit }}` | a1b2c3d | Short HEAD commit SHA |-| `{{ remote }}` | origin | Primary remote name |-| `{{ remote_url }}` | [email protected]:user/repo.git | Remote URL |-| `{{ upstream }}` | origin/feature | Upstream tracking branch |-| `{{ target }}` | main | Target branch (merge hooks only) |-| `{{ base }}` | main | Base branch (creation hooks only) |-| `{{ base_worktree_path }}` | /path/to/myproject | Base branch worktree (creation hooks only) |+| Variable | Description |+|----------|-------------|+| `{{ repo }}` | Repository directory name |+| `{{ repo_path }}` | Absolute path to repository root |+| `{{ branch }}` | Branch name |+| `{{ worktree_name }}` | Worktree directory name |+| `{{ worktree_path }}` | Absolute worktree path |+| `{{ primary_worktree_path }}` | Main worktree path (for bare repos: default branch worktree) |+| `{{ default_branch }}` | Default branch name |+| `{{ commit }}` | Full HEAD commit SHA |+| `{{ short_commit }}` | Short HEAD commit SHA (7 chars) |+| `{{ remote }}` | Primary remote name |+| `{{ remote_url }}` | Remote URL |+| `{{ upstream }}` | Upstream tracking branch |+| `{{ target }}` | Target branch (merge hooks only) |+| `{{ base }}` | Base branch (creation hooks only) |+| `{{ base_worktree_path }}` | Base branch worktree (creation hooks only) |### Worktrunk Filters@@ -1236,6 +1280,25 @@ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")The JSON includes all template variables plus `hook_type` and `hook_name`.+## Running hooks manually++`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.++```console+wt hook pre-merge # Run all pre-merge hooks+wt hook pre-merge test # Run hooks named "test" from both sources+wt hook pre-merge user: # Run all user hooks+wt hook pre-merge project: # Run all project hooks+wt hook pre-merge user:test # Run only user's "test" hook+wt hook pre-merge project:test # Run only project's "test" hook+wt hook pre-merge --yes # Skip approval prompts (for CI)+wt hook post-create --var branch=feature/test # Override template variable+```++The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.++The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.+## Designing effective hooks### post-create vs post-start@@ -1317,117 +1380,9 @@ EOF"""```-## Security--Project commands require approval on first run:--```-▲ repo needs approval to execute 3 commands:+### Progressive validation-○ post-create install:- echo 'Installing dependencies...'--❯ Allow and remember? [y/N]-```--- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)-- If a command changes, new approval is required-- Use `--yes` to bypass prompts (useful for CI/automation)-- Use `--no-verify` to skip hooks--Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.--## User hooks--Define hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval.--```toml-# ~/.config/worktrunk/config.toml-[post-create]-setup = "echo 'Setting up worktree...'"--[pre-merge]-notify = "notify-send 'Merging {{ branch }}'"-```--User hooks support the same hook types and template variables as project hooks.--**Key differences from project hooks:**--| Aspect | Project hooks | User hooks |-|--------|--------------|------------|-| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` |-| Scope | Single repository | All repositories |-| Approval | Required | Not required |-| Execution order | After user hooks | Before project hooks |--Skip hooks with `--no-verify`. To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.--**Use cases:**-- Personal notifications or logging-- Editor/IDE integration-- Repository-agnostic setup tasks-- Filtering by repository using JSON context--**Filtering by repository:**--User hooks receive JSON context on stdin, enabling repository-specific behavior:--```toml-# ~/.config/worktrunk/config.toml-[post-create]-gitlab-setup = """-python3 -c '-import json, sys, subprocess-ctx = json.load(sys.stdin)-if "gitlab" in ctx.get("remote", ""):- subprocess.run(["glab", "mr", "create", "--fill"])-'-"""-```--## Running hooks manually--`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.--```console-wt hook pre-merge # Run all pre-merge hooks-wt hook pre-merge test # Run hooks named "test" from both sources-wt hook pre-merge user: # Run all user hooks-wt hook pre-merge project: # Run all project hooks-wt hook pre-merge user:test # Run only user's "test" hook-wt hook pre-merge project:test # Run only project's "test" hook-wt hook pre-merge --yes # Skip approval prompts (for CI)-wt hook post-create --var branch=feature/test # Override template variable-```--The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.--The `--var KEY=VALUE` flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.--## Language-specific tips--Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes). This section covers hooks.--### Python--Use `uv sync` to recreate virtual environments:--```toml-[post-create]-install = "uv sync"-```--For pip-based projects without uv:--```toml-[post-create]-venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"-```--### Hook flow patterns--**Progressive validation** — Quick checks before commit, thorough validation before merge:+Quick checks before commit, thorough validation before merge:```toml[pre-commit]@@ -1439,7 +1394,9 @@ test = "npm test"build = "npm run build"```-**Target-specific behavior** — Different actions for production vs staging:+### Target-specific behavior++Different actions for production vs staging:```tomlpost-merge = """@@ -1451,6 +1408,17 @@ fi"""```+### Python virtual environments++Use `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):++```toml+[post-create]+install = "uv sync"+```++For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes).+## See also- [`wt merge`](@/merge.md) — Runs hooks automatically during merge