Skip to content

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

docs(hook): move progressive-validation and target-specific examples to tips-patterns (#2329)

Maximilian Roos18825c3e3c3b
diff --git a/docs/content/hook.md b/docs/content/hook.md
index fb5484291..b9de7f6b6 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -308,39 +308,13 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-## Progressive validation
-
-Quick checks before commit, thorough validation before merge:
-
-```toml
-[[pre-commit]]
-lint = "npm run lint"
-typecheck = "npm run typecheck"
-
-[[pre-merge]]
-test = "npm test"
-build = "npm run build"
-```
-
-## Target-specific behavior
-
-Different actions for production vs staging:
-
-```toml
-post-merge = """
-if [ {{ target }} = main ]; then
- npm run deploy:production
-elif [ {{ target }} = staging ]; then
- npm run deploy:staging
-fi
-"""
-```
-
## More recipes
- Copy gitignored files between worktrees: `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copy — see [Tips & Patterns](@/tips-patterns.md#eliminate-cold-starts)
- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — see [Tips & Patterns](@/tips-patterns.md#dev-server-per-worktree)
- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](@/config.md#wt-config-state-vars) that later hooks reference — see [Tips & Patterns](@/tips-patterns.md#database-per-worktree)
+- Progressive validation: quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge` — see [Tips & Patterns](@/tips-patterns.md#progressive-validation)
+- Target-specific behavior: branch on `{{ target }}` in `post-merge` for per-environment deploys — see [Tips & Patterns](@/tips-patterns.md#target-specific-hooks)
## See also
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index a0bb8fcc5..a996cbdfc 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -216,6 +216,38 @@ Reference Taskfile/Justfile/Makefile in hooks:
"validate" = "just test lint"
```
+## Progressive validation
+
+Split checks across hook types — quick feedback before each commit, expensive suites before merge:
+
+```toml
+[[pre-commit]]
+lint = "npm run lint"
+typecheck = "npm run typecheck"
+
+[[pre-merge]]
+test = "npm test"
+build = "npm run build"
+```
+
+`pre-commit` runs on every squash commit during `wt merge`; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.
+
+## Target-specific hooks
+
+Branch on `{{ target }}` to vary behavior per merge destination — for example, deploying to production from `main` and staging from a release branch:
+
+```toml
+post-merge = """
+if [ {{ target }} = main ]; then
+ npm run deploy:production
+elif [ {{ target }} = staging ]; then
+ npm run deploy:staging
+fi
+"""
+```
+
+`{{ target }}` is the branch being merged into. `post-merge` runs in the target's worktree (or the primary worktree if target has none), so deploy commands see the merged code.
+
## Shortcuts
Special arguments work across all commands—see [`wt switch`](@/switch.md#shortcuts) for the full list.
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index c2a1e2735..b57e92cee 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -307,39 +307,13 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-## Progressive validation
-
-Quick checks before commit, thorough validation before merge:
-
-```toml
-[[pre-commit]]
-lint = "npm run lint"
-typecheck = "npm run typecheck"
-
-[[pre-merge]]
-test = "npm test"
-build = "npm run build"
-```
-
-## Target-specific behavior
-
-Different actions for production vs staging:
-
-```toml
-post-merge = """
-if [ {{ target }} = main ]; then
- npm run deploy:production
-elif [ {{ target }} = staging ]; then
- npm run deploy:staging
-fi
-"""
-```
-
## More recipes
- Copy gitignored files between worktrees: `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copy — https://worktrunk.dev/tips-patterns/#eliminate-cold-starts
- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree
- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](https://worktrunk.dev/config/#wt-config-state-vars) that later hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree
+- Progressive validation: quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge` — https://worktrunk.dev/tips-patterns/#progressive-validation
+- Target-specific behavior: branch on `{{ target }}` in `post-merge` for per-environment deploys — https://worktrunk.dev/tips-patterns/#target-specific-hooks
## Command reference
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 37ba574b3..1e7addd3e 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -221,6 +221,38 @@ Reference Taskfile/Justfile/Makefile in hooks:
"validate" = "just test lint"
```
+## Progressive validation
+
+Split checks across hook types — quick feedback before each commit, expensive suites before merge:
+
+```toml
+[[pre-commit]]
+lint = "npm run lint"
+typecheck = "npm run typecheck"
+
+[[pre-merge]]
+test = "npm test"
+build = "npm run build"
+```
+
+`pre-commit` runs on every squash commit during `wt merge`; `pre-merge` runs once per merge after the rebase, so it's the right place for the slow tests.
+
+## Target-specific hooks
+
+Branch on `{{ target }}` to vary behavior per merge destination — for example, deploying to production from `main` and staging from a release branch:
+
+```toml
+post-merge = """
+if [ {{ target }} = main ]; then
+ npm run deploy:production
+elif [ {{ target }} = staging ]; then
+ npm run deploy:staging
+fi
+"""
+```
+
+`{{ target }}` is the branch being merged into. `post-merge` runs in the target's worktree (or the primary worktree if target has none), so deploy commands see the merged code.
+
## Shortcuts
Special arguments work across all commands—see [`wt switch`](https://worktrunk.dev/switch/#shortcuts) for the full list.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 5f8f5efc0..598797205 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1448,39 +1448,13 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-## Progressive validation
-
-Quick checks before commit, thorough validation before merge:
-
-```toml
-[[pre-commit]]
-lint = "npm run lint"
-typecheck = "npm run typecheck"
-
-[[pre-merge]]
-test = "npm test"
-build = "npm run build"
-```
-
-## Target-specific behavior
-
-Different actions for production vs staging:
-
-```toml
-post-merge = """
-if [ {{ target }} = main ]; then
- npm run deploy:production
-elif [ {{ target }} = staging ]; then
- npm run deploy:staging
-fi
-"""
-```
-
## More recipes
- Copy gitignored files between worktrees: `wt step copy-ignored` in `post-start` shares build caches and dependencies; use a `[[post-start]]` pipeline when a later hook depends on the copy — https://worktrunk.dev/tips-patterns/#eliminate-cold-starts
- Dev server per worktree: `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree
- Database per worktree: a `post-start` pipeline stores container name, port, and connection string as [per-branch vars](@/config.md#wt-config-state-vars) that later hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree
+- Progressive validation: quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge` — https://worktrunk.dev/tips-patterns/#progressive-validation
+- Target-specific behavior: branch on `{{ target }}` in `post-merge` for per-environment deploys — https://worktrunk.dev/tips-patterns/#target-specific-hooks
## See also
diff --git a/src/help.rs b/src/help.rs
index 4ec1d15d2..75db498ed 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -540,6 +540,14 @@ fn post_process_for_html(text: &str) -> String {
"depends on the copy — https://worktrunk.dev/tips-patterns/#eliminate-cold-starts",
"depends on the copy — see [Tips & Patterns](@/tips-patterns.md#eliminate-cold-starts)",
)
+ .replace(
+ "expensive tests and builds in `pre-merge` — https://worktrunk.dev/tips-patterns/#progressive-validation",
+ "expensive tests and builds in `pre-merge` — see [Tips & Patterns](@/tips-patterns.md#progressive-validation)",
+ )
+ .replace(
+ "per-environment deploys — https://worktrunk.dev/tips-patterns/#target-specific-hooks",
+ "per-environment deploys — see [Tips & Patterns](@/tips-patterns.md#target-specific-hooks)",
+ )
// Approval prompt: plain code block → terminal shortcode with colored symbols
// and gutter. CLI shows a plain ``` block; web shows styled terminal output
// matching the actual CLI appearance (yellow ▲, dim ○, cyan ❯, gutter bar).