Skip to content

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

docs(hook): consolidate copy-ignored recipe and trim redundant examples (#2323)

Maximilian Roos064f8940c0fc
diff --git a/docs/content/hook.md b/docs/content/hook.md
index b254ec9fa..93ccb7736 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -319,16 +319,6 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:
-
-```toml
-[[pre-start]]
-copy = "wt step copy-ignored"
-
-[[pre-start]]
-install = "pnpm install"
-```
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -357,62 +347,9 @@ fi
"""
```
-## Python virtual environments
-
-Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
-
-```toml
-[pre-start]
-install = "uv sync"
-```
-
-For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes).
-
-## Hook type examples
-
-```toml
-post-merge = "cargo install --path ."
-
-[[pre-start]]
-install = "npm ci"
-env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
-
-[[pre-commit]]
-format = "cargo fmt -- --check"
-lint = "cargo clippy -- -D warnings"
-
-[[pre-merge]]
-test = "cargo test"
-build = "cargo build --release"
-
-[pre-switch]
-pull = """
-FETCH_HEAD="$(git rev-parse --git-common-dir)/FETCH_HEAD"
-if [ "$(find "$FETCH_HEAD" -mmin +360 2>/dev/null)" ] || [ ! -f "$FETCH_HEAD" ]; then
- git pull
-fi
-"""
-
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-
-[post-start]
-copy = "wt step copy-ignored"
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-commit]
-notify = "curl -s https://ci.example.com/trigger?branch={{ branch }}"
-
-[pre-remove]
-archive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"
-
-[post-remove]
-kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
-```
-
## 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)
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 5dc215c01..a0bb8fcc5 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -120,21 +120,19 @@ Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored
copy = "wt step copy-ignored"
```
-Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
-
-All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.
-
-## Local CI gate
-
-`pre-merge` hooks run before merging. Failures abort the merge:
+When another hook depends on the copy — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages — sequence them with a `[[post-start]]` pipeline:
```toml
-[[pre-merge]]
-lint = "uv run ruff check"
-test = "uv run pytest"
+[[post-start]]
+copy = "wt step copy-ignored"
+
+[[post-start]]
+install = "pnpm install"
```
-This catches issues locally before pushing — like running CI locally.
+Use `pre-start` instead when an `--execute` command needs the copied files immediately.
+
+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.
## Manual commit messages
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 5e2849a62..7c02fe17e 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -318,16 +318,6 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:
-
-```toml
-[[pre-start]]
-copy = "wt step copy-ignored"
-
-[[pre-start]]
-install = "pnpm install"
-```
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -356,62 +346,9 @@ fi
"""
```
-## Python virtual environments
-
-Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
-
-```toml
-[pre-start]
-install = "uv sync"
-```
-
-For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](https://worktrunk.dev/step/#language-specific-notes).
-
-## Hook type examples
-
-```toml
-post-merge = "cargo install --path ."
-
-[[pre-start]]
-install = "npm ci"
-env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
-
-[[pre-commit]]
-format = "cargo fmt -- --check"
-lint = "cargo clippy -- -D warnings"
-
-[[pre-merge]]
-test = "cargo test"
-build = "cargo build --release"
-
-[pre-switch]
-pull = """
-FETCH_HEAD="$(git rev-parse --git-common-dir)/FETCH_HEAD"
-if [ "$(find "$FETCH_HEAD" -mmin +360 2>/dev/null)" ] || [ ! -f "$FETCH_HEAD" ]; then
- git pull
-fi
-"""
-
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-
-[post-start]
-copy = "wt step copy-ignored"
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-commit]
-notify = "curl -s https://ci.example.com/trigger?branch={{ branch }}"
-
-[pre-remove]
-archive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"
-
-[post-remove]
-kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
-```
-
## 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
diff --git a/skills/worktrunk/reference/tips-patterns.md b/skills/worktrunk/reference/tips-patterns.md
index 9d6379ad7..37ba574b3 100644
--- a/skills/worktrunk/reference/tips-patterns.md
+++ b/skills/worktrunk/reference/tips-patterns.md
@@ -115,21 +115,19 @@ Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) t
copy = "wt step copy-ignored"
```
-Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.
-
-All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.
-
-## Local CI gate
-
-`pre-merge` hooks run before merging. Failures abort the merge:
+When another hook depends on the copy — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages — sequence them with a `[[post-start]]` pipeline:
```toml
-[[pre-merge]]
-lint = "uv run ruff check"
-test = "uv run pytest"
+[[post-start]]
+copy = "wt step copy-ignored"
+
+[[post-start]]
+install = "pnpm install"
```
-This catches issues locally before pushing — like running CI locally.
+Use `pre-start` instead when an `--execute` command needs the copied files immediately.
+
+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.
## Manual commit messages
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index b940b50a5..5b2a0026b 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1459,16 +1459,6 @@ Git worktrees share the repository but not untracked files. [`wt step copy-ignor
copy = "wt step copy-ignored"
```
-Use `pre-start` instead if subsequent hooks need the copied files — for example, copying `node_modules/` before `pnpm install` so the install reuses cached packages:
-
-```toml
-[[pre-start]]
-copy = "wt step copy-ignored"
-
-[[pre-start]]
-install = "pnpm install"
-```
-
## Progressive validation
Quick checks before commit, thorough validation before merge:
@@ -1497,62 +1487,9 @@ fi
"""
```
-## Python virtual environments
-
-Use `uv sync` to recreate virtual environments, or `python -m venv .venv && .venv/bin/pip install -r requirements.txt` for pip-based projects:
-
-```toml
-[pre-start]
-install = "uv sync"
-```
-
-For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes).
-
-## Hook type examples
-
-```toml
-post-merge = "cargo install --path ."
-
-[[pre-start]]
-install = "npm ci"
-env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
-
-[[pre-commit]]
-format = "cargo fmt -- --check"
-lint = "cargo clippy -- -D warnings"
-
-[[pre-merge]]
-test = "cargo test"
-build = "cargo build --release"
-
-[pre-switch]
-pull = """
-FETCH_HEAD="$(git rev-parse --git-common-dir)/FETCH_HEAD"
-if [ "$(find "$FETCH_HEAD" -mmin +360 2>/dev/null)" ] || [ ! -f "$FETCH_HEAD" ]; then
- git pull
-fi
-"""
-
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-
-[post-start]
-copy = "wt step copy-ignored"
-server = "npm run dev -- --port {{ branch | hash_port }}"
-
-[post-commit]
-notify = "curl -s https://ci.example.com/trigger?branch={{ branch }}"
-
-[pre-remove]
-archive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"
-
-[post-remove]
-kill-server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"
-remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
-```
-
## 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
diff --git a/src/help.rs b/src/help.rs
index 2d3d8b563..4ec1d15d2 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -536,6 +536,10 @@ fn post_process_for_html(text: &str) -> String {
"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)",
+ )
// 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).