Skip to content

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

Document hooks in user config (#1845)

Maximilian Roos491108a7828f
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 47cadc080..1f107295c 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -131,6 +131,24 @@
#
# Aliases defined here apply to all projects. For project-specific aliases, use the project config (https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
#
+# ### Hooks
+#
+# See `wt hook --help` for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks (https://worktrunk.dev/config/#project-configuration) apply only to that repository.
+#
+# # Single command
+# pre-start = "npm ci"
+#
+# # Multiple named commands (concurrent for post-*, sequential for pre-*)
+# [pre-merge]
+# test = "npm test"
+# build = "npm run build"
+#
+# # Pipeline — list of maps, run in order (each map concurrent)
+# post-start = [
+# { install = "npm ci" },
+# { build = "npm run build", server = "npm run dev" }
+# ]
+#
# ### User project-specific settings
#
# For context:
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 0023950a5..4a142f351 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -6,24 +6,7 @@
#
# ## Hooks
#
-# See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-#
-# Single command:
-#
-# pre-start = "npm ci"
-#
-# Multiple named commands (concurrent for post-*, sequential for pre-*):
-#
-# [pre-merge]
-# test = "npm test"
-# build = "npm run build"
-#
-# Pipeline — list of maps, run in order (each map concurrent):
-#
-# post-start = [
-# { install = "npm ci" },
-# { build = "npm run build", server = "npm run dev" }
-# ]
+# Project hooks apply to this repository only. Format is the same as user hooks (https://worktrunk.dev/config/#hooks); see `wt hook --help` for hook types, execution order, and examples.
#
# ## Dev server URL
#
diff --git a/docs/content/config.md b/docs/content/config.md
index e1d1bdd11..da78e3ee4 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -223,6 +223,26 @@ url = "echo http://localhost:{{ branch | hash_port }}"
Aliases defined here apply to all projects. For project-specific aliases, use the [project config](@/config.md#project-configuration) `[aliases]` section instead.
+### Hooks
+
+See `wt hook --help` for hook types, execution order, template variables, and examples. User hooks apply to all projects; [project hooks](@/config.md#project-configuration) apply only to that repository.
+
+```toml
+# Single command
+pre-start = "npm ci"
+
+# Multiple named commands (concurrent for post-*, sequential for pre-*)
+[pre-merge]
+test = "npm test"
+build = "npm run build"
+
+# Pipeline — list of maps, run in order (each map concurrent)
+post-start = [
+ { install = "npm ci" },
+ { build = "npm run build", server = "npm run dev" }
+]
+```
+
### User project-specific settings
For context:
@@ -346,30 +366,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-
-Single command:
-
-```toml
-pre-start = "npm ci"
-```
-
-Multiple named commands (concurrent for post-*, sequential for pre-*):
-
-```toml
-[pre-merge]
-test = "npm test"
-build = "npm run build"
-```
-
-Pipeline — list of maps, run in order (each map concurrent):
-
-```toml
-post-start = [
- { install = "npm ci" },
- { build = "npm run build", server = "npm run dev" }
-]
-```
+Project hooks apply to this repository only. Format is the same as [user hooks](@/config.md#hooks); see `wt hook --help` for hook types, execution order, and examples.
## Dev server URL
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 08673dc4d..75c7e910c 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -222,6 +222,26 @@ url = "echo http://localhost:{{ branch | hash_port }}"
Aliases defined here apply to all projects. For project-specific aliases, use the [project config](https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
+### Hooks
+
+See `wt hook --help` for hook types, execution order, template variables, and examples. User hooks apply to all projects; [project hooks](https://worktrunk.dev/config/#project-configuration) apply only to that repository.
+
+```toml
+# Single command
+pre-start = "npm ci"
+
+# Multiple named commands (concurrent for post-*, sequential for pre-*)
+[pre-merge]
+test = "npm test"
+build = "npm run build"
+
+# Pipeline — list of maps, run in order (each map concurrent)
+post-start = [
+ { install = "npm ci" },
+ { build = "npm run build", server = "npm run dev" }
+]
+```
+
### User project-specific settings
For context:
@@ -345,30 +365,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-
-Single command:
-
-```toml
-pre-start = "npm ci"
-```
-
-Multiple named commands (concurrent for post-*, sequential for pre-*):
-
-```toml
-[pre-merge]
-test = "npm test"
-build = "npm run build"
-```
-
-Pipeline — list of maps, run in order (each map concurrent):
-
-```toml
-post-start = [
- { install = "npm ci" },
- { build = "npm run build", server = "npm run dev" }
-]
-```
+Project hooks apply to this repository only. Format is the same as [user hooks](https://worktrunk.dev/config/#hooks); see `wt hook --help` for hook types, execution order, and examples.
## Dev server URL
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 19c4f448f..6be4ef867 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1799,6 +1799,26 @@ url = "echo http://localhost:{{ branch | hash_port }}"
Aliases defined here apply to all projects. For project-specific aliases, use the [project config](@/config.md#project-configuration) `[aliases]` section instead.
+### Hooks
+
+See `wt hook --help` for hook types, execution order, template variables, and examples. User hooks apply to all projects; [project hooks](@/config.md#project-configuration) apply only to that repository.
+
+```toml
+# Single command
+pre-start = "npm ci"
+
+# Multiple named commands (concurrent for post-*, sequential for pre-*)
+[pre-merge]
+test = "npm test"
+build = "npm run build"
+
+# Pipeline — list of maps, run in order (each map concurrent)
+post-start = [
+ { install = "npm ci" },
+ { build = "npm run build", server = "npm run dev" }
+]
+```
+
### User project-specific settings
For context:
@@ -1922,30 +1942,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-
-Single command:
-
-```toml
-pre-start = "npm ci"
-```
-
-Multiple named commands (concurrent for post-*, sequential for pre-*):
-
-```toml
-[pre-merge]
-test = "npm test"
-build = "npm run build"
-```
-
-Pipeline — list of maps, run in order (each map concurrent):
-
-```toml
-post-start = [
- { install = "npm ci" },
- { build = "npm run build", server = "npm run dev" }
-]
-```
+Project hooks apply to this repository only. Format is the same as [user hooks](@/config.md#hooks); see `wt hook --help` for hook types, execution order, and examples.
## Dev server URL
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index c5cea439d..5d9154a25 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -190,6 +190,24 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # Aliases defined here apply to all projects. For project-specific aliases, use the project config (https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.
  #
+  # ### Hooks
+  #
+  # See `wt hook --help` for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks (https://worktrunk.dev/config/#project-configuration) apply only to that repository.
+  #
+  # # Single command
+  # pre-start = "npm ci"
+  #
+  # # Multiple named commands (concurrent for post-*, sequential for pre-*)
+  # [pre-merge]
+  # test = "npm test"
+  # build = "npm run build"
+  #
+  # # Pipeline — list of maps, run in order (each map concurrent)
+  # post-start = [
+  # { install = "npm ci" },
+  # { build = "npm run build", server = "npm run dev" }
+  # ]
+  #
  # ### User project-specific settings
  #
  # For context:
@@ -310,24 +328,7 @@ With --project, creates .config/wt.toml in the current repositor
  #
  # ## Hooks
  #
-  # See `wt hook --help` for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-  #
-  # Single command:
-  #
-  # pre-start = "npm ci"
-  #
-  # Multiple named commands (concurrent for post-*, sequential for pre-*):
-  #
-  # [pre-merge]
-  # test = "npm test"
-  # build = "npm run build"
-  #
-  # Pipeline — list of maps, run in order (each map concurrent):
-  #
-  # post-start = [
-  # { install = "npm ci" },
-  # { build = "npm run build", server = "npm run dev" }
-  # ]
+  # Project hooks apply to this repository only. Format is the same as user hooks (https://worktrunk.dev/config/#hooks); see `wt hook --help` for hook types, execution order, and examples.
  #
  # ## Dev server URL
  #
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 9b6d46ba7..702a86ad5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -236,6 +236,24 @@ Command templates that run with wt step <name>. See wt step alia
Aliases defined here apply to all projects. For project-specific aliases, use the project config [aliases] section instead.
+Hooks
+
+See wt hook --help for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks apply only to that repository.
+
+  # Single command
+  pre-start = "npm ci"
+ 
+  # Multiple named commands (concurrent for post-*, sequential for pre-*)
+  [pre-merge]
+  test = "npm test"
+  build = "npm run build"
+ 
+  # Pipeline — list of maps, run in order (each map concurrent)
+  post-start = [
+   { install = "npm ci" },
+   { build = "npm run build", server = "npm run dev" }
+  ]
+
User project-specific settings
For context:
@@ -347,24 +365,7 @@ Location: .config/wt.toml (checked into version control and shared with
Hooks
-See wt hook --help for hook types, execution order, template variables, and examples. Both project and user configs support hooks in the same format.
-
-Single command:
-
-  pre-start = "npm ci"
-
-Multiple named commands (concurrent for post-*, sequential for pre-*):
-
-  [pre-merge]
-  test = "npm test"
-  build = "npm run build"
-
-Pipeline — list of maps, run in order (each map concurrent):
-
-  post-start = [
-   { install = "npm ci" },
-   { build = "npm run build", server = "npm run dev" }
-  ]
+Project hooks apply to this repository only. Format is the same as user hooks; see wt hook --help for hook types, execution order, and examples.
Dev server URL