Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(hook): say that post-* hooks from the two sources run concurrently (#4020)
Maximilian Roos24d1a8d15ecf
diff --git a/CLAUDE.md b/CLAUDE.mdindex bb09de6d6..19a22432d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -150,6 +150,10 @@ Why: wt installs a `signal_hook` SIGINT/SIGTERM handler so it can forward signal**Implementation:** the operation-driven hooks (`pre-merge`, `post-merge`, `pre-remove`, `post-remove`, `post-switch`, `pre-start`, `post-start`) are gated *before* a state mutation and run *after* it, so a second config read could select an unapproved command. `src/commands/hook_plan.rs` closes this structurally: each gate (`wt remove` / `wt merge` / `wt step prune` / `wt switch`) selects the command set once into an immutable `ApprovedHookPlan` (`HookPlan::approve`); the executor consumes only that value via `execute_planned_hook` / `register_planned` and holds no `ProjectConfig` to re-derive from, so re-selection is a compile error, not a review check. An empty plan (`--no-hooks`, declined, or no project config) runs nothing. The adjacent hooks with no gate→exec mutation (`pre-commit`, `post-commit`, `pre-switch`, `wt hook <type>`, aliases) still resolve config at invocation via `execute_hook` / `HookAnnouncer::register`. See `src/commands/hook_plan.rs` and the `commands::hooks` module spec.+### Background Hook Pipelines Run Concurrently, Per Source++A `post-*` batch spawns one detached pipeline per source, and they run at once. Don't serialize them: `post-start` is documented for dev servers and `wt step tether`, so a user hook that never exits would block the project's forever, and `wt merge`'s batch spans two worktrees (`post-commit` anchors on the invoking worktree, the rest on the destination) so chaining also drops hooks behind a head whose worktree is already removed. The cost is that two hooks touching one worktree's git state can collide — two `git pull`s there append to each other's `FETCH_HEAD` and both fail — which `wt hook --help` tells users to avoid by keeping dependent commands in one source.+## Hook Output Logs`.git/wt/logs/` layout — per-branch and repo-wide log paths, plus the `sanitize_for_filename` filename rule: the `HookLog` spec in `src/commands/process.rs`. The top-level file-vs-directory split that `wt config state` walks: the "Log layout invariant" in `src/commands/config/state.rs`.diff --git a/docs/src/content/docs/hook.md b/docs/src/content/docs/hook.mdindex 1b298fe5f..332332c59 100644--- a/docs/src/content/docs/hook.md+++ b/docs/src/content/docs/hook.md@@ -110,10 +110,12 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependenc| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` || Scope | Single repository | All repositories (or [per-project](/config/#user-project-specific-settings)) || Approval | Required | Not required |-| Execution order | After user hooks | First |+| Execution order | `pre-*`: after user hooks. `post-*`: alongside them | `pre-*`: first. `post-*`: alongside project hooks |To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.+A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline — they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+## Template variablesHooks can use template variables that expand at runtime:diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.mdindex 2cde87d8e..1f19703d3 100644--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md@@ -104,10 +104,12 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependenc| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` || Scope | Single repository | All repositories (or [per-project](https://worktrunk.dev/config/#user-project-specific-settings)) || Approval | Required | Not required |-| Execution order | After user hooks | First |+| Execution order | `pre-*`: after user hooks. `post-*`: alongside them | `pre-*`: first. `post-*`: alongside project hooks |To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.+A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline — they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+## Template variablesHooks can use template variables that expand at runtime:diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 2cde87d8e..1f19703d3 100644--- a/skills/worktrunk/reference/hook.md+++ b/skills/worktrunk/reference/hook.md@@ -104,10 +104,12 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependenc| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` || Scope | Single repository | All repositories (or [per-project](https://worktrunk.dev/config/#user-project-specific-settings)) || Approval | Required | Not required |-| Execution order | After user hooks | First |+| Execution order | `pre-*`: after user hooks. `post-*`: alongside them | `pre-*`: first. `post-*`: alongside project hooks |To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.+A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline — they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+## Template variablesHooks can use template variables that expand at runtime:diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 6bd06be44..c28d687e3 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1666,10 +1666,12 @@ Most hooks don't need `[[hook]]` blocks. Reach for them when there's a dependenc| Location | `.config/wt.toml` | `~/.config/worktrunk/config.toml` || Scope | Single repository | All repositories (or [per-project](/config/#user-project-specific-settings)) || Approval | Required | Not required |-| Execution order | After user hooks | First |+| Execution order | `pre-*`: after user hooks. `post-*`: alongside them | `pre-*`: first. `post-*`: alongside project hooks |To run a specific hook when user and project both define the same name, use `user:name` or `project:name` syntax.+A `pre-*` hook blocks the command, so both sources run as one pipeline: user commands first, and a failure there skips the project's. A `post-*` hook runs in the background, where each source is its own detached pipeline — they start together, neither waits for the other, and a failure in one leaves the other running. Order within a source is still yours to set with `[[hook]]` blocks; across `post-*` sources there is none. Two `post-*` hooks that write the same file, or run `git` in the same worktree, will race, so put commands that depend on each other in one source.+## Template variablesHooks can use template variables that expand at runtime: