Skip to content

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

Clarify hook execution order and types

Maximilian Roos6e1f5c0fc13b
diff --git a/.claude-plugin/skills/worktrunk/reference/user-config.md b/.claude-plugin/skills/worktrunk/reference/user-config.md
index 0cac8bf23..62c2d7835 100644
--- a/.claude-plugin/skills/worktrunk/reference/user-config.md
+++ b/.claude-plugin/skills/worktrunk/reference/user-config.md
@@ -297,7 +297,7 @@ User hooks support the same hook types and template variables as project hooks.
| Location | `~/.config/worktrunk/config.toml` | `.config/wt.toml` |
| Scope | All repositories | Single repository |
| Approval | Not required | Required |
-| Execution order | First | After user hooks |
+| Execution order | Before project hooks | After user hooks |
**Filtering by repository:**
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 5de0e2316..3361d24d8 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -8,13 +8,14 @@ group = "Reference"
## What commands does Worktrunk execute?
-Worktrunk executes commands in three contexts:
+Worktrunk executes commands in four contexts:
-1. **Project hooks** (`.config/wt.toml`) — Automation for worktree lifecycle
-2. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
-3. **--execute flag** — Explicitly provided commands
+1. **User hooks** (`~/.config/worktrunk/config.toml`) — Personal automation for all repositories
+2. **Project hooks** (`.config/wt.toml`) — Repository-specific automation
+3. **LLM commands** (`~/.config/worktrunk/config.toml`) — Commit message generation
+4. **--execute flag** — Explicitly provided commands
-Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
+User hooks don't require approval (you defined them). Commands from project hooks require approval on first run. Approved commands are saved to user config. If a command changes, Worktrunk requires new approval.
### Example approval prompt
diff --git a/docs/content/merge.md b/docs/content/merge.md
index 65836a47d..753a68635 100644
--- a/docs/content/merge.md
+++ b/docs/content/merge.md
@@ -55,11 +55,11 @@ wt merge --no-commit
1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted changes become a separate commit and individual commits are preserved.
2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
-3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+3. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
-5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+5. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+7. **Post-merge hooks** — Hooks run after cleanup. Failures are logged but don't abort.
Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
diff --git a/src/cli.rs b/src/cli.rs
index c8f3b1e99..2fb0efb1f 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2533,11 +2533,11 @@ wt merge --no-commit
1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted changes become a separate commit and individual commits are preserved.
2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
-3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+3. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
-5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+5. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+7. **Post-merge hooks** — Hooks run after cleanup. Failures are logged but don't abort.
Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
index 2add29f89..f87f6a40e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -113,12 +113,12 @@ wt merge --no-commit
control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted
changes become a separate commit and individual commits are preserved.
2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
-3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+3. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
-5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+5. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree,
the worktree is preserved.
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+7. **Post-merge hooks** — Hooks run after cleanup. Failures are logged but don't abort.
Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is
passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 3ddd6baef..69e9cb5eb 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -104,12 +104,12 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
control what gets staged: all (default), tracked, or none. A backup ref is saved to refs/wt-backup/<branch>. With --no-squash, uncommitted
changes become a separate commit and individual commits are preserved.
2. Rebase — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
-3. Pre-merge hooks — Project commands run after rebase, before merge. Failures abort. See wt hook.
+3. Pre-merge hooks — Hooks run after rebase, before merge. Failures abort. See wt hook.
4. Merge — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
-5. Pre-remove hooks — Project commands run before removing worktree. Failures abort.
+5. Pre-remove hooks — Hooks run before removing worktree. Failures abort.
6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch or in the main worktree,
the worktree is preserved.
-7. Post-merge hooks — Project commands run after cleanup. Failures are logged but don't abort.
+7. Post-merge hooks — Hooks run after cleanup. Failures are logged but don't abort.
Use --no-commit to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless --no-rebase is
passed. Useful after preparing commits manually with wt step. Requires a clean working tree.
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
index c0907a61f..47049397a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -67,11 +67,11 @@ wt merge --no-commit
1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted changes become a separate commit and individual commits are preserved.
2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
-3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+3. **Pre-merge hooks** — Hooks run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
-5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+5. **Pre-remove hooks** — Hooks run before removing worktree. Failures abort.
6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
-7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+7. **Post-merge hooks** — Hooks run after cleanup. Failures are logged but don't abort.
Use `--no-commit` to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless `--no-rebase` is passed. Useful after preparing commits manually with `wt step`. Requires a clean working tree.