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.mdindex 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 SafetyNever 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.tomlindex 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.tomlindex 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.mdindex 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 settingsFor 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.```tomlpre-start = "npm ci"diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 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 settingsFor 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.```tomlpre-start = "npm ci"diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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 settingsFor 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.```tomlpre-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.snapindex 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 [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m#[0m[107m [0m [2m# Aliases defined here apply to all projects. For project-specific aliases, use the project config (https://worktrunk.dev/config/#project-configuration) `[aliases]` section instead.[0m[107m [0m [2m#[0m-[107m [0m [2m# ### Hooks[0m-[107m [0m [2m#[0m-[107m [0m [2m# 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.[0m-[107m [0m [2m#[0m-[107m [0m [2m# # Single command[0m-[107m [0m [2m# pre-start = "npm ci"[0m-[107m [0m [2m#[0m-[107m [0m [2m# # Multiple named commands (concurrent for post-*, sequential for pre-*)[0m-[107m [0m [2m# [pre-merge][0m-[107m [0m [2m# test = "npm test"[0m-[107m [0m [2m# build = "npm run build"[0m-[107m [0m [2m#[0m-[107m [0m [2m# # Pipeline — list of maps, run in order (each map concurrent)[0m-[107m [0m [2m# post-start = [[0m-[107m [0m [2m# { install = "npm ci" },[0m-[107m [0m [2m# { build = "npm run build", server = "npm run dev" }[0m-[107m [0m [2m# ][0m-[107m [0m [2m#[0m[107m [0m [2m# ### User project-specific settings[0m[107m [0m [2m#[0m[107m [0m [2m# For context:[0m@@ -315,6 +297,27 @@ Creates [2m~/.config/worktrunk/config.toml[0m with the following content:[107m [0m [2m#[0m[107m [0m [2m# """[0m[107m [0m [2m# <!-- DEFAULT_SQUASH_TEMPLATE_END -->[0m+[107m [0m [2m#[0m+[107m [0m [2m# ## Hooks[0m+[107m [0m [2m#[0m+[107m [0m [2m# 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.[0m+[107m [0m [2m#[0m+[107m [0m [2m# Single command:[0m+[107m [0m [2m#[0m+[107m [0m [2m# pre-start = "npm ci"[0m+[107m [0m [2m#[0m+[107m [0m [2m# Multiple named commands (concurrent for post-*, sequential for pre-*):[0m+[107m [0m [2m#[0m+[107m [0m [2m# [pre-merge][0m+[107m [0m [2m# test = "npm test"[0m+[107m [0m [2m# build = "npm run build"[0m+[107m [0m [2m#[0m+[107m [0m [2m# Pipeline — list of maps, run in order (each map concurrent):[0m+[107m [0m [2m#[0m+[107m [0m [2m# post-start = [[0m+[107m [0m [2m# { install = "npm ci" },[0m+[107m [0m [2m# { build = "npm run build", server = "npm run dev" }[0m+[107m [0m [2m# ][0m[1m[32mProject config[0m@@ -328,7 +331,7 @@ With [2m--project[0m, creates [2m.config/wt.toml[0m in the current repositor[107m [0m [2m#[0m[107m [0m [2m# ## Hooks[0m[107m [0m [2m#[0m-[107m [0m [2m# 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.[0m+[107m [0m [2m# Project hooks apply to this repository only. See `wt hook` (https://worktrunk.dev/hook/) for hook types, execution order, and examples.[0m[107m [0m [2m#[0m[107m [0m [2m# pre-start = "npm ci"[0m[107m [0m [2m# post-start = "npm run dev"[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snapindex 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 [2mwt step <name>[0m. See [2mwt step[0m aliaAliases defined here apply to all projects. For project-specific aliases, use the project config [2m[aliases][0m section instead.-[32mHooks[0m--See [2mwt hook --help[0m for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks apply only to that repository.--[107m [0m [2m# Single command[0m-[107m [0m [2mpre-start = [0m[2m[32m"npm ci"[0m-[107m [0m-[107m [0m [2m# Multiple named commands (concurrent for post-*, sequential for pre-*)[0m-[107m [0m [2m[36m[pre-merge][0m-[107m [0m [2mtest = [0m[2m[32m"npm test"[0m-[107m [0m [2mbuild = [0m[2m[32m"npm run build"[0m-[107m [0m-[107m [0m [2m# Pipeline — list of maps, run in order (each map concurrent)[0m-[107m [0m [2mpost-start = [[0m-[107m [0m [2m { install = [0m[2m[32m"npm ci"[0m[2m },[0m-[107m [0m [2m { build = [0m[2m[32m"npm run build"[0m[2m, server = [0m[2m[32m"npm run dev"[0m[2m }[0m-[107m [0m [2m][0m-[32mUser project-specific settings[0mFor context:@@ -357,6 +339,27 @@ Default template:[107m [0m [2m[32m</diff>[0m[107m [0m[107m [0m [2m[32m"[0m[2m[32m""[0m++[1m[32mHooks[0m++See [2mwt hook[0m for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks apply only to that repository.++Single command:++[107m [0m [2mpre-start = [0m[2m[32m"npm ci"[0m++Multiple named commands (concurrent for post-*, sequential for pre-*):++[107m [0m [2m[36m[pre-merge][0m+[107m [0m [2mtest = [0m[2m[32m"npm test"[0m+[107m [0m [2mbuild = [0m[2m[32m"npm run build"[0m++Pipeline — list of maps, run in order (each map concurrent):++[107m [0m [2mpost-start = [[0m+[107m [0m [2m { install = [0m[2m[32m"npm ci"[0m[2m },[0m+[107m [0m [2m { build = [0m[2m[32m"npm run build"[0m[2m, server = [0m[2m[32m"npm run dev"[0m[2m }[0m+[107m [0m [2m][0m[32mPROJECT CONFIGURATION[0mCreate with [2mwt config create --project[0m. Examples shown — uncomment and customize for your project.@@ -365,7 +368,7 @@ Location: [2m.config/wt.toml[0m (checked into version control and shared with[1m[32mHooks[0m-Project hooks apply to this repository only. Format is the same as user hooks; see [2mwt hook --help[0m for hook types, execution order, and examples.+Project hooks apply to this repository only. See [2mwt hook[0m for hook types, execution order, and examples.[107m [0m [2mpre-start = [0m[2m[32m"npm ci"[0m[107m [0m [2mpost-start = [0m[2m[32m"npm run dev"[0m