Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Group hook help into navigational sections (#1359)
Maximilian Roos6d8415f58c77
diff --git a/docs/content/hook.md b/docs/content/hook.mdindex daba9fe3c..e48cac96e 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -13,7 +13,7 @@ Run configured hooks.Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.-## Hook types+# Hook Types| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|@@ -34,7 +34,7 @@ Background hooks show a single-line summary by default. Use `-v` to see expandedThe most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.-### pre-switch+## pre-switchRuns before every `wt switch` — before branch validation or worktree creation. Useful for ensuring the repository is up to date before switching. Template variables reflect the current worktree (the source), not the destination. Failure aborts the switch.@@ -49,7 +49,7 @@ fi"""```-### post-start+## post-startDev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.@@ -59,7 +59,7 @@ copy = "wt step copy-ignored"server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-create+## post-createTasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.@@ -69,7 +69,7 @@ install = "npm ci"env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```-### post-switch+## post-switchTriggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.@@ -78,7 +78,7 @@ Triggers on all switch results: creating new worktrees, switching to existing ontmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"```-### pre-commit+## pre-commitFormatters, linters, type checking — runs during `wt merge` before the squash commit.@@ -88,7 +88,7 @@ format = "cargo fmt -- --check"lint = "cargo clippy -- -D warnings"```-### pre-merge+## pre-mergeTests, security scans, build verification — runs after rebase, before merge to target.@@ -98,7 +98,7 @@ test = "cargo test"build = "cargo build --release"```-### post-merge+## post-mergeDeployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.@@ -106,7 +106,7 @@ Deployment, notifications, installing updated binaries. Runs in the target brancpost-merge = "cargo install --path ."```-### pre-remove+## pre-removeCleanup tasks before worktree is deleted, saving test artifacts, backing up state. Runs in the worktree being removed, with access to worktree files.@@ -115,7 +115,7 @@ Cleanup tasks before worktree is deleted, saving test artifacts, backing up statarchive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"```-### post-remove+## post-removeCleanup tasks after worktree removal: stopping dev servers, removing containers, notifying external systems. All template variables reference the removed worktree, so cleanup scripts can identify resources to clean up. Output logged to `.git/wt-logs/{branch}-{source}-post-remove-{name}.log`.@@ -127,7 +127,7 @@ remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/nullDuring `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-remove → post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.-## Security+# SecurityProject commands require approval on first run:@@ -147,11 +147,11 @@ Project commands require approval on first run:Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.-## Configuration+# ConfigurationHooks can be defined in two places: project config (`.config/wt.toml`) for repository-specific automation, or user config (`~/.config/worktrunk/config.toml`) for personal automation across all repositories.-### Project hooks+## Project hooksProject hooks are defined in `.config/wt.toml`. They can be a single command or multiple named commands:@@ -165,7 +165,7 @@ test = "cargo test"build = "cargo build --release"```-### User hooks+## User hooksDefine hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).@@ -196,7 +196,7 @@ Skip hooks with `--no-verify`. To run a specific hook when user and project both- Editor/IDE integration- Repository-agnostic setup tasks-### Template variables+## Template variablesHooks can use template variables that expand at runtime:@@ -226,7 +226,7 @@ Some variables may not be defined: `upstream` is only set when the branch trackssync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-### Worktrunk filters+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -252,7 +252,7 @@ dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.-### Worktrunk functions+## Worktrunk functionsTemplates also support functions for dynamic lookups:@@ -268,7 +268,7 @@ The `worktree_path_of_branch` function returns the filesystem path of a worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"```-### JSON context+## JSON contextHooks receive context as JSON on stdin, enabling complex logic that templates can't express:@@ -282,7 +282,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:The JSON includes all template variables plus `hook_type` and `hook_name`.-## Running hooks manually+# 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.@@ -301,9 +301,9 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`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+# Designing Effective Hooks-### post-start vs post-create+## post-start vs post-createBoth run when creating a worktree. The difference:@@ -316,7 +316,7 @@ Many tasks work well in `post-start` — they'll likely be ready by the time theBackground processes spawned by `post-start` outlive the worktree — pair them with `post-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.-### Copying untracked files+## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:@@ -327,7 +327,7 @@ copy = "wt step copy-ignored"Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Dev servers+## Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:@@ -353,7 +353,7 @@ For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomaiserver = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"```-### Databases+## DatabasesEach worktree can have its own database. Docker containers get unique names and ports:@@ -387,7 +387,7 @@ EOF"""```-### Progressive validation+## Progressive validationQuick checks before commit, thorough validation before merge:@@ -401,7 +401,7 @@ test = "npm test"build = "npm run build"```-### Target-specific behavior+## Target-specific behaviorDifferent actions for production vs staging:@@ -415,7 +415,7 @@ fi"""```-### Python virtual environments+## Python virtual environmentsUse `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex d0c07d52c..c0df156a8 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -4,7 +4,7 @@ Run configured hooks.Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.-## Hook types+# Hook Types| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|@@ -25,7 +25,7 @@ Background hooks show a single-line summary by default. Use `-v` to see expandedThe most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.-### pre-switch+## pre-switchRuns before every `wt switch` — before branch validation or worktree creation. Useful for ensuring the repository is up to date before switching. Template variables reflect the current worktree (the source), not the destination. Failure aborts the switch.@@ -40,7 +40,7 @@ fi"""```-### post-start+## post-startDev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.@@ -50,7 +50,7 @@ copy = "wt step copy-ignored"server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-create+## post-createTasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.@@ -60,7 +60,7 @@ install = "npm ci"env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```-### post-switch+## post-switchTriggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.@@ -69,7 +69,7 @@ Triggers on all switch results: creating new worktrees, switching to existing ontmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"```-### pre-commit+## pre-commitFormatters, linters, type checking — runs during `wt merge` before the squash commit.@@ -79,7 +79,7 @@ format = "cargo fmt -- --check"lint = "cargo clippy -- -D warnings"```-### pre-merge+## pre-mergeTests, security scans, build verification — runs after rebase, before merge to target.@@ -89,7 +89,7 @@ test = "cargo test"build = "cargo build --release"```-### post-merge+## post-mergeDeployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.@@ -97,7 +97,7 @@ Deployment, notifications, installing updated binaries. Runs in the target brancpost-merge = "cargo install --path ."```-### pre-remove+## pre-removeCleanup tasks before worktree is deleted, saving test artifacts, backing up state. Runs in the worktree being removed, with access to worktree files.@@ -106,7 +106,7 @@ Cleanup tasks before worktree is deleted, saving test artifacts, backing up statarchive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"```-### post-remove+## post-removeCleanup tasks after worktree removal: stopping dev servers, removing containers, notifying external systems. All template variables reference the removed worktree, so cleanup scripts can identify resources to clean up. Output logged to `.git/wt-logs/{branch}-{source}-post-remove-{name}.log`.@@ -118,7 +118,7 @@ remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/nullDuring `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-remove → post-merge. See [`wt merge`](https://worktrunk.dev/merge/#pipeline) for the complete pipeline.-## Security+# SecurityProject commands require approval on first run:@@ -138,11 +138,11 @@ Project commands require approval on first run:Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.-## Configuration+# ConfigurationHooks can be defined in two places: project config (`.config/wt.toml`) for repository-specific automation, or user config (`~/.config/worktrunk/config.toml`) for personal automation across all repositories.-### Project hooks+## Project hooksProject hooks are defined in `.config/wt.toml`. They can be a single command or multiple named commands:@@ -156,7 +156,7 @@ test = "cargo test"build = "cargo build --release"```-### User hooks+## User hooksDefine hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](https://worktrunk.dev/config/#setting-overrides-experimental).@@ -187,7 +187,7 @@ Skip hooks with `--no-verify`. To run a specific hook when user and project both- Editor/IDE integration- Repository-agnostic setup tasks-### Template variables+## Template variablesHooks can use template variables that expand at runtime:@@ -217,7 +217,7 @@ Some variables may not be defined: `upstream` is only set when the branch trackssync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-### Worktrunk filters+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -243,7 +243,7 @@ dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.-### Worktrunk functions+## Worktrunk functionsTemplates also support functions for dynamic lookups:@@ -259,7 +259,7 @@ The `worktree_path_of_branch` function returns the filesystem path of a worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"```-### JSON context+## JSON contextHooks receive context as JSON on stdin, enabling complex logic that templates can't express:@@ -273,7 +273,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:The JSON includes all template variables plus `hook_type` and `hook_name`.-## Running hooks manually+# 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.@@ -292,9 +292,9 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`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+# Designing Effective Hooks-### post-start vs post-create+## post-start vs post-createBoth run when creating a worktree. The difference:@@ -307,7 +307,7 @@ Many tasks work well in `post-start` — they'll likely be ready by the time theBackground processes spawned by `post-start` outlive the worktree — pair them with `post-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.-### Copying untracked files+## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:@@ -318,7 +318,7 @@ copy = "wt step copy-ignored"Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Dev servers+## Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:@@ -344,7 +344,7 @@ For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomaiserver = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"```-### Databases+## DatabasesEach worktree can have its own database. Docker containers get unique names and ports:@@ -378,7 +378,7 @@ EOF"""```-### Progressive validation+## Progressive validationQuick checks before commit, thorough validation before merge:@@ -392,7 +392,7 @@ test = "npm test"build = "npm run build"```-### Target-specific behavior+## Target-specific behaviorDifferent actions for production vs staging:@@ -406,7 +406,7 @@ fi"""```-### Python virtual environments+## Python virtual environmentsUse `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 934c0835d..4a51f6d10 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1077,7 +1077,7 @@ Alias names that match a built-in step command (`commit`, `squash`, etc.) are shname = "hook",after_long_help = r#"Hooks are shell commands that run at key points in the worktree lifecycle — automatically during `wt switch`, `wt merge`, & `wt remove`, or on demand via `wt hook <type>`. Both user (`~/.config/worktrunk/config.toml`) and project (`.config/wt.toml`) hooks are supported.-## Hook types+# Hook Types| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|@@ -1098,7 +1098,7 @@ Background hooks show a single-line summary by default. Use `-v` to see expandedThe most common starting point is `post-start` — it runs background tasks (dev servers, file copying, builds) when creating a worktree.-### pre-switch+## pre-switchRuns before every `wt switch` — before branch validation or worktree creation. Useful for ensuring the repository is up to date before switching. Template variables reflect the current worktree (the source), not the destination. Failure aborts the switch.@@ -1113,7 +1113,7 @@ fi"""```-### post-start+## post-startDev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.@@ -1123,7 +1123,7 @@ copy = "wt step copy-ignored"server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-create+## post-createTasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.@@ -1133,7 +1133,7 @@ install = "npm ci"env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```-### post-switch+## post-switchTriggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Output logged to `.git/wt-logs/{branch}-{source}-post-switch-{name}.log`.@@ -1142,7 +1142,7 @@ Triggers on all switch results: creating new worktrees, switching to existing ontmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"```-### pre-commit+## pre-commitFormatters, linters, type checking — runs during `wt merge` before the squash commit.@@ -1152,7 +1152,7 @@ format = "cargo fmt -- --check"lint = "cargo clippy -- -D warnings"```-### pre-merge+## pre-mergeTests, security scans, build verification — runs after rebase, before merge to target.@@ -1162,7 +1162,7 @@ test = "cargo test"build = "cargo build --release"```-### post-merge+## post-mergeDeployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.@@ -1170,7 +1170,7 @@ Deployment, notifications, installing updated binaries. Runs in the target brancpost-merge = "cargo install --path ."```-### pre-remove+## pre-removeCleanup tasks before worktree is deleted, saving test artifacts, backing up state. Runs in the worktree being removed, with access to worktree files.@@ -1179,7 +1179,7 @@ Cleanup tasks before worktree is deleted, saving test artifacts, backing up statarchive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"```-### post-remove+## post-removeCleanup tasks after worktree removal: stopping dev servers, removing containers, notifying external systems. All template variables reference the removed worktree, so cleanup scripts can identify resources to clean up. Output logged to `.git/wt-logs/{branch}-{source}-post-remove-{name}.log`.@@ -1191,7 +1191,7 @@ remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/nullDuring `wt merge`, hooks run in this order: pre-commit → pre-merge → pre-remove → post-remove → post-merge. See [`wt merge`](@/merge.md#pipeline) for the complete pipeline.-## Security+# SecurityProject commands require approval on first run:@@ -1211,11 +1211,11 @@ Project commands require approval on first run:Manage approvals with `wt hook approvals add` and `wt hook approvals clear`.-## Configuration+# ConfigurationHooks can be defined in two places: project config (`.config/wt.toml`) for repository-specific automation, or user config (`~/.config/worktrunk/config.toml`) for personal automation across all repositories.-### Project hooks+## Project hooksProject hooks are defined in `.config/wt.toml`. They can be a single command or multiple named commands:@@ -1229,7 +1229,7 @@ test = "cargo test"build = "cargo build --release"```-### User hooks+## User hooksDefine hooks in `~/.config/worktrunk/config.toml` to run for all repositories. User hooks run before project hooks and don't require approval. For repository-specific user hooks, see [setting overrides](@/config.md#setting-overrides-experimental).@@ -1260,7 +1260,7 @@ Skip hooks with `--no-verify`. To run a specific hook when user and project both- Editor/IDE integration- Repository-agnostic setup tasks-### Template variables+## Template variablesHooks can use template variables that expand at runtime:@@ -1290,7 +1290,7 @@ Some variables may not be defined: `upstream` is only set when the branch trackssync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"```-### Worktrunk filters+## Worktrunk filtersTemplates support Jinja2 filters for transforming values:@@ -1316,7 +1316,7 @@ dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"Variables are shell-escaped automatically — quotes around `{{ ... }}` are unnecessary and can cause issues with special characters.-### Worktrunk functions+## Worktrunk functionsTemplates also support functions for dynamic lookups:@@ -1332,7 +1332,7 @@ The `worktree_path_of_branch` function returns the filesystem path of a worktreesetup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"```-### JSON context+## JSON contextHooks receive context as JSON on stdin, enabling complex logic that templates can't express:@@ -1346,7 +1346,7 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:The JSON includes all template variables plus `hook_type` and `hook_name`.-## Running hooks manually+# 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.@@ -1365,9 +1365,9 @@ The `user:` and `project:` prefixes filter by source. Use `user:` or `project:`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+# Designing Effective Hooks-### post-start vs post-create+## post-start vs post-createBoth run when creating a worktree. The difference:@@ -1380,7 +1380,7 @@ Many tasks work well in `post-start` — they'll likely be ready by the time theBackground processes spawned by `post-start` outlive the worktree — pair them with `post-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.-### Copying untracked files+## Copying untracked filesGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:@@ -1391,7 +1391,7 @@ copy = "wt step copy-ignored"Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.-### Dev servers+## Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:@@ -1417,7 +1417,7 @@ For subdomain-based routing (useful for cookies/CORS), use `.localhost` subdomaiserver = "npm run dev -- --host {{ branch | sanitize }}.localhost --port {{ branch | hash_port }}"```-### Databases+## DatabasesEach worktree can have its own database. Docker containers get unique names and ports:@@ -1451,7 +1451,7 @@ EOF"""```-### Progressive validation+## Progressive validationQuick checks before commit, thorough validation before merge:@@ -1465,7 +1465,7 @@ test = "npm test"build = "npm run build"```-### Target-specific behavior+## Target-specific behaviorDifferent actions for production vs staging:@@ -1479,7 +1479,7 @@ fi"""```-### Python virtual environments+## Python virtual environmentsUse `uv sync` to recreate virtual environments (or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects):