Skip to content

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

Improve hooks documentation (#366)

Maximilian Roos53c604468c70
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 8321f18f8..ac5a21370 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -8,23 +8,9 @@ group = "Commands"
<!-- ⚠️ AUTO-GENERATED from `wt hook --help-page` — edit cli.rs to update -->
-Run hooks independently of normal worktree operations.
+Shell commands that run at key points in the worktree lifecycle.
-Hooks normally run automatically during `wt switch --create`, `wt merge`, and `wt remove`. This command runs them on demand — useful for testing hooks during development, running in CI pipelines, or re-running after a failure.
-
-Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
-
-```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)
-```
-
-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.
+Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
## Hook types
@@ -339,6 +325,22 @@ frontend-tests = "cd frontend && npm test"
backend-tests = "cd backend && cargo test"
```
+## 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)
+```
+
+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.
+
### Common patterns
**Fast dependencies + slow build** — Install blocking, build in background:
diff --git a/src/cli.rs b/src/cli.rs
index 4c435fba8..dee5b1894 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1014,7 +1014,10 @@ pub enum HookCommand {
///
/// Blocking — waits for completion before continuing.
PostCreate {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1027,7 +1030,10 @@ pub enum HookCommand {
///
/// Background — runs without blocking.
PostStart {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1040,7 +1046,10 @@ pub enum HookCommand {
///
/// Background — runs without blocking.
PostSwitch {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1051,7 +1060,10 @@ pub enum HookCommand {
/// Run pre-commit hooks
PreCommit {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1062,7 +1074,10 @@ pub enum HookCommand {
/// Run pre-merge hooks
PreMerge {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1073,7 +1088,10 @@ pub enum HookCommand {
/// Run post-merge hooks
PostMerge {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1084,7 +1102,10 @@ pub enum HookCommand {
/// Run pre-remove hooks
PreRemove {
- /// Run only this command from hook config
+ /// Filter by command name
+ ///
+ /// Supports `user:name` or `project:name` to filter by source.
+ /// `user:` alone runs all user hooks; `project:` alone runs all project hooks.
#[arg(add = crate::completion::hook_command_name_completer())]
name: Option<String>,
@@ -1457,23 +1478,9 @@ wt step push
/// Run hooks independently
#[command(
name = "hook",
- after_long_help = r#"Run hooks independently of normal worktree operations.
-
-Hooks normally run automatically during `wt switch --create`, `wt merge`, and `wt remove`. This command runs them on demand — useful for testing hooks during development, running in CI pipelines, or re-running after a failure.
-
-Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
-
-```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)
-```
+ after_long_help = r#"Shell commands that run at key points in the worktree lifecycle.
-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.
+Hooks run automatically during `wt switch`, `wt merge`, & `wt remove`. `wt hook <type>` runs them on demand. Both user hooks (from `~/.config/worktrunk/config.toml`) and project hooks (from `.config/wt.toml`) are supported.
## Hook types
@@ -1788,6 +1795,22 @@ frontend-tests = "cd frontend && npm test"
backend-tests = "cd backend && cargo test"
```
+## 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)
+```
+
+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.
+
### Common patterns
**Fast dependencies + slow build** — Install blocking, build in background: