Skip to content

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

docs(hook): restructure recipes list and callout for copy-ignored (#2349)

Maximilian Roos970375afd417
diff --git a/docs/content/hook.md b/docs/content/hook.md
index d3660812f..75ae09220 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -234,6 +234,15 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
subprocess.run(['make', 'seed-db'])
```
+## Copying untracked files
+
+One specific command worth calling out: [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:
+
+```toml
+[post-start]
+copy = "wt step copy-ignored"
+```
+
# 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.
@@ -250,24 +259,13 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Designing Effective Hooks
-
-## Copying untracked files
-
-Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:
-
-```toml
-[post-start]
-copy = "wt step copy-ignored"
-```
-
-## More recipes
+## 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)
+- [Eliminate cold starts](@/tips-patterns.md#eliminate-cold-starts): `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
+- [Dev server per worktree](@/tips-patterns.md#dev-server-per-worktree): `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing
+- [Database per worktree](@/tips-patterns.md#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
+- [Progressive validation](@/tips-patterns.md#progressive-validation): quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge`
+- [Target-specific hooks](@/tips-patterns.md#target-specific-hooks): branch on `{{ target }}` in `post-merge` for per-environment deploys
## See also
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index afd692673..3d5567e0a 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -225,6 +225,15 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
subprocess.run(['make', 'seed-db'])
```
+## Copying untracked files
+
+One specific command worth calling out: [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:
+
+```toml
+[post-start]
+copy = "wt step copy-ignored"
+```
+
# 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.
@@ -251,24 +260,13 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Designing Effective Hooks
-
-## Copying untracked files
-
-Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:
-
-```toml
-[post-start]
-copy = "wt step copy-ignored"
-```
-
-## More recipes
+## 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
+- [Eliminate cold starts](https://worktrunk.dev/tips-patterns/#eliminate-cold-starts): `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
+- [Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree): `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing
+- [Database per worktree](https://worktrunk.dev/tips-patterns/#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
+- [Progressive validation](https://worktrunk.dev/tips-patterns/#progressive-validation): quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge`
+- [Target-specific hooks](https://worktrunk.dev/tips-patterns/#target-specific-hooks): branch on `{{ target }}` in `post-merge` for per-environment deploys
## Command reference
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index ec7d19f52..63290d8bf 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1366,6 +1366,15 @@ if ctx['branch'].startswith('feature/') and 'backend' in ctx['repo']:
subprocess.run(['make', 'seed-db'])
```
+## Copying untracked files
+
+One specific command worth calling out: [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored). Git worktrees share the repository but not untracked files, and this copies gitignored files between worktrees:
+
+```toml
+[post-start]
+copy = "wt step copy-ignored"
+```
+
# 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.
@@ -1392,24 +1401,13 @@ Any `--KEY=VALUE` whose key isn't referenced by a hook template forwards into `{
The long form `--var KEY=VALUE` is deprecated but still supported. It force-binds regardless of whether any hook template references `KEY` — useful when a template only references the key conditionally (e.g. `{% if override %}…{% endif %}`).
-# Designing Effective Hooks
-
-## Copying untracked files
-
-Git worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:
-
-```toml
-[post-start]
-copy = "wt step copy-ignored"
-```
-
-## More recipes
+## 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
+- [Eliminate cold starts](@/tips-patterns.md#eliminate-cold-starts): `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
+- [Dev server per worktree](@/tips-patterns.md#dev-server-per-worktree): `hash_port` in `post-start` for launch and `post-remove` for cleanup, with optional subdomain routing
+- [Database per worktree](@/tips-patterns.md#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
+- [Progressive validation](@/tips-patterns.md#progressive-validation): quick lint/typecheck in `pre-commit`, expensive tests and builds in `pre-merge`
+- [Target-specific hooks](@/tips-patterns.md#target-specific-hooks): branch on `{{ target }}` in `post-merge` for per-environment deploys
## See also
diff --git a/src/help.rs b/src/help.rs
index 75db498ed..4545f6ec8 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -526,28 +526,6 @@ fn post_process_for_html(text: &str) -> String {
"Open an issue at https://github.com/max-sixty/worktrunk.",
"[Open an issue](https://github.com/max-sixty/worktrunk/issues).",
)
- // Tips & Patterns recipe bullets: bare URLs (terminal auto-links) in CLI,
- // inline markdown links on the web.
- .replace(
- "routing — https://worktrunk.dev/tips-patterns/#dev-server-per-worktree",
- "routing — see [Tips & Patterns](@/tips-patterns.md#dev-server-per-worktree)",
- )
- .replace(
- "hooks reference — https://worktrunk.dev/tips-patterns/#database-per-worktree",
- "hooks reference — see [Tips & Patterns](@/tips-patterns.md#database-per-worktree)",
- )
- .replace(
- "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).