Skip to content

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

Document hooks in user config, fix config doc comment style (#1861)

Maximilian Roos36aec6b09086
diff --git a/CLAUDE.md b/CLAUDE.md
index e23a22fc2..7b4dd6c5a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -165,6 +165,10 @@ After editing `after_long_help` text, also update the help snapshots:
cargo insta test --accept -- --test integration "test_help"
```
+### Config doc TOML blocks
+
+Config docs (`USER_CONFIG_START`/`PROJECT_CONFIG_START` sections in `src/cli/mod.rs`) generate `dev/*.example.toml` files where every line is commented out with `#`. TOML comments inside code blocks become double-commented (`# # comment`). Use plain text descriptions ending with colons before each code block instead — inline end-of-line comments (e.g., `key = "value" # explanation`) are fine.
+
## Data Safety
Never risk data loss without explicit user consent. A failed command that preserves data is better than a "successful" command that silently destroys work.
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 2b73c53c7..9c7f5c888 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -131,24 +131,6 @@
#
# 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:
@@ -256,3 +238,24 @@
#
# """
# <!-- DEFAULT_SQUASH_TEMPLATE_END -->
+#
+# ## Hooks
+#
+# See `wt hook` (https://worktrunk.dev/hook/) 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" }
+# ]
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 3fbbc14e8..48f1e3e99 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -6,7 +6,7 @@
#
# ## Hooks
#
-# 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.
+# Project hooks apply to this repository only. See `wt hook` (https://worktrunk.dev/hook/) for hook types, execution order, and examples.
#
# pre-start = "npm ci"
# post-start = "npm run dev"
diff --git a/docs/content/config.md b/docs/content/config.md
index a3d5f93e5..5f90b08ac 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -223,26 +223,6 @@ 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:
@@ -356,6 +336,33 @@ squash-template = """
"""
```
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
+
+## Hooks
+
+See [`wt hook`](@/hook.md) 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.
+
+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" }
+]
+```
<!-- USER_CONFIG_END -->
<!-- PROJECT_CONFIG_START -->
# Project Configuration
@@ -366,7 +373,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-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.
+Project hooks apply to this repository only. See [`wt hook`](@/hook.md) for hook types, execution order, and examples.
```toml
pre-start = "npm ci"
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 0b522f16f..0f4059308 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -222,26 +222,6 @@ 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:
@@ -355,6 +335,33 @@ squash-template = """
"""
```
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
+
+## Hooks
+
+See [`wt hook`](https://worktrunk.dev/hook/) 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:
+
+```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" }
+]
+```
<!-- USER_CONFIG_END -->
<!-- PROJECT_CONFIG_START -->
# Project Configuration
@@ -365,7 +372,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-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.
+Project hooks apply to this repository only. See [`wt hook`](https://worktrunk.dev/hook/) for hook types, execution order, and examples.
```toml
pre-start = "npm ci"
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 12eebd8c1..2229338b7 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1799,26 +1799,6 @@ 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:
@@ -1932,6 +1912,33 @@ squash-template = """
"""
```
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
+
+## Hooks
+
+See [`wt hook`](@/hook.md) 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.
+
+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" }
+]
+```
<!-- USER_CONFIG_END -->
<!-- PROJECT_CONFIG_START -->
# Project Configuration
@@ -1942,7 +1949,7 @@ Location: `.config/wt.toml` (checked into version control and shared with the te
## Hooks
-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.
+Project hooks apply to this repository only. See [`wt hook`](@/hook.md) for hook types, execution order, and examples.
```toml
pre-start = "npm ci"
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 37245d938..fa50c6115 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -190,24 +190,6 @@ 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:
@@ -315,6 +297,27 @@ Creates ~/.config/worktrunk/config.toml with the following content:
  #
  # """
  # <!-- DEFAULT_SQUASH_TEMPLATE_END -->
+  #
+  # ## Hooks
+  #
+  # See `wt hook` (https://worktrunk.dev/hook/) 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" }
+  # ]
Project config
@@ -328,7 +331,7 @@ With --project, creates .config/wt.toml in the current repositor
  #
  # ## Hooks
  #
-  # 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.
+  # Project hooks apply to this repository only. See `wt hook` (https://worktrunk.dev/hook/) for hook types, execution order, and examples.
  #
  # pre-start = "npm ci"
  # post-start = "npm run dev"
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 74051cab0..6a001b105 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -236,24 +236,6 @@ 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:
@@ -357,6 +339,27 @@ Default template:
  </diff>
 
  """
+
+Hooks
+
+See wt hook 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" }
+  ]
PROJECT CONFIGURATION
Create with wt config create --project. Examples shown — uncomment and customize for your project.
@@ -365,7 +368,7 @@ Location: .config/wt.toml (checked into version control and shared with
Hooks
-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.
+Project hooks apply to this repository only. See wt hook for hook types, execution order, and examples.
  pre-start = "npm ci"
  post-start = "npm run dev"