Skip to content

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

docs: add comprehensive hook design guide (#367)

Maximilian Roos74f72ac9b353
diff --git a/docs/content/hook.md b/docs/content/hook.md
index ac5a21370..25b460be7 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -188,6 +188,117 @@ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")
The JSON includes all template variables plus `hook_type` and `hook_name`.
+## Designing effective hooks
+
+### post-create vs post-start
+
+Both run when creating a worktree. The difference:
+
+| Hook | Execution | Best for |
+|------|-----------|----------|
+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |
+| `post-start` | Background, parallel | Long-running tasks that can finish while you work |
+
+Many tasks work well in `post-start` — they'll likely be ready by the time you need them, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
+
+### Copying untracked files
+
+Git worktrees share the repository but not untracked files. Common files to copy or link:
+
+- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`
+- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`
+- **Generated assets**: Images, ML models, binaries too large for git
+- **Environment files**: `.env` (if not generated per-worktree)
+
+Three strategies:
+
+| Strategy | Speed | Disk | State |
+|----------|-------|------|-------|
+| **Symlink** | Instant | Shared | Shared (changes affect all worktrees) |
+| **Copy** | Slow | Full duplicate | Isolated |
+| **Copy-on-write** | Instant | Shared until modified | Isolated |
+
+### Copy-on-write for disk efficiency
+
+Copy-on-write (CoW) creates instant clones that share disk space until modified. Perfect for large directories.
+
+| OS | Filesystem | Command |
+|----|------------|---------|
+| macOS | APFS | `cp -c` |
+| Linux | Btrfs, XFS | `cp --reflink=auto` |
+| Windows | ReFS | No shell equivalent (requires API) |
+
+Cross-platform pattern that auto-detects and falls back gracefully:
+
+```toml
+[post-create]
+deps = """
+if cp -c /dev/null /dev/null 2>/dev/null; then
+ cp -c -r {{ repo_root }}/node_modules .
+elif cp --reflink=auto /dev/null /dev/null 2>/dev/null; then
+ cp --reflink=auto -r {{ repo_root }}/node_modules .
+else
+ cp -r {{ repo_root }}/node_modules .
+fi
+"""
+```
+
+### Dev servers
+
+Run a dev server per worktree on a deterministic port using `hash_port`:
+
+```toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+```
+
+The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
+
+```toml
+[list]
+url = "http://localhost:{{ branch | hash_port }}"
+```
+
+For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:
+
+```toml
+[post-start]
+server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+```
+
+### Databases
+
+Each worktree can have its own database. Docker containers get unique names and ports:
+
+```toml
+[post-start]
+db = """
+docker run -d --rm \
+ --name {{ repo }}-{{ branch | sanitize }}-postgres \
+ -p {{ 'db-' ~ branch | hash_port }}:5432 \
+ -e POSTGRES_DB={{ repo }} \
+ -e POSTGRES_PASSWORD=dev \
+ postgres:16
+"""
+
+[pre-remove]
+db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+```
+
+The `'db-' ~ branch` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+
+Generate `.env.local` with the connection string:
+
+```toml
+[post-create]
+env = """
+cat > .env.local << EOF
+DATABASE_URL=postgres://postgres:dev@localhost:{{ 'db-' ~ branch | hash_port }}/{{ repo }}
+DEV_PORT={{ branch | hash_port }}
+EOF
+"""
+```
+
## Security
Project commands require approval on first run:
@@ -257,99 +368,76 @@ if "gitlab" in ctx.get("remote", ""):
"""
```
-## Examples
+## Running hooks manually
-### Node.js / TypeScript
+`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
-```toml
-[post-create]
-install = "npm ci"
+```bash
+wt hook pre-merge # Run all pre-merge hooks
+wt hook pre-merge test # Run hooks named "test" from both sources
+wt hook pre-merge user: # Run all user hooks
+wt hook pre-merge project: # Run all project hooks
+wt hook pre-merge user:test # Run only user's "test" hook
+wt hook pre-merge project:test # Run only project's "test" hook
+wt hook pre-merge --yes # Skip approval prompts (for CI)
+```
-[post-start]
-dev = "npm run dev"
+The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
-[pre-commit]
-lint = "npm run lint"
-typecheck = "npm run typecheck"
+## Language-specific tips
-[pre-merge]
-test = "npm test"
-build = "npm run build"
-```
+Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.
### Rust
-```toml
-[post-create]
-build = "cargo build"
+The `target/` directory is huge (often 1-10GB) and benefits most from CoW. Worktrunk's own config seeds compiled dependencies:
-[pre-commit]
-format = "cargo fmt -- --check"
-clippy = "cargo clippy -- -D warnings"
+```toml
+[post-start]
+deps = """
+[ -d {{ repo_root }}/target/debug/deps ] && [ ! -e target ] &&
+mkdir -p target/debug/deps &&
+cp -c {{ repo_root }}/target/debug/deps/*.rlib {{ repo_root }}/target/debug/deps/*.rmeta target/debug/deps/ &&
+cp -cR {{ repo_root }}/target/debug/.fingerprint {{ repo_root }}/target/debug/build target/debug/
+"""
+```
-[pre-merge]
-test = "cargo test"
-build = "cargo build --release"
+This cuts first build from ~68s to ~3s by reusing compiled dependencies. The check `[ ! -e target ]` skips if target already exists.
-[post-merge]
-install = "cargo install --path ."
-```
+### Python
-### Python (uv)
+Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:
```toml
[post-create]
install = "uv sync"
-
-[pre-commit]
-format = "uv run ruff format --check ."
-lint = "uv run ruff check ."
-
-[pre-merge]
-test = "uv run pytest"
-typecheck = "uv run mypy ."
```
-### Monorepo
+For pip-based projects without uv:
```toml
[post-create]
-frontend = "cd frontend && npm ci"
-backend = "cd backend && cargo build"
-
-[post-start]
-database = "docker-compose up -d postgres"
-
-[pre-merge]
-frontend-tests = "cd frontend && npm test"
-backend-tests = "cd backend && cargo test"
+venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"
```
-## Running hooks manually
+### Node.js
-`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
+`node_modules/` is large but mostly static. CoW works well:
-```bash
-wt hook pre-merge # Run all pre-merge hooks
-wt hook pre-merge test # Run hooks named "test" from both sources
-wt hook pre-merge user: # Run all user hooks
-wt hook pre-merge project: # Run all project hooks
-wt hook pre-merge user:test # Run only user's "test" hook
-wt hook pre-merge project:test # Run only project's "test" hook
-wt hook pre-merge --yes # Skip approval prompts (for CI)
+```toml
+[post-create]
+deps = "cp -c -r {{ repo_root }}/node_modules . 2>/dev/null || npm ci"
```
-The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
-
-### Common patterns
-
-**Fast dependencies + slow build** — Install blocking, build in background:
+If the project has no native dependencies, symlinks are even faster:
```toml
-post-create = "npm install"
-post-start = "npm run build"
+[post-create]
+deps = "ln -sf {{ repo_root }}/node_modules ."
```
+### Hook flow patterns
+
**Progressive validation** — Quick checks before commit, thorough validation before merge:
```toml
@@ -362,7 +450,7 @@ test = "npm test"
build = "npm run build"
```
-**Target-specific behavior**:
+**Target-specific behavior** — Different actions for production vs staging:
```toml
post-merge = """
@@ -374,14 +462,6 @@ fi
"""
```
-**Symlinks and caches** — The `{{ repo_root }}` variable points to the main worktree:
-
-```toml
-[post-create]
-cache = "ln -sf {{ repo_root }}/node_modules node_modules"
-env = "cp {{ repo_root }}/.env.local .env"
-```
-
## See also
- [wt merge](@/merge.md) — Runs hooks automatically during merge
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index 9762afb77..c7452edcd 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -28,7 +28,7 @@ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
"install" = "npm ci"
```
-See [Worktrunk's own `.config/wt.toml`](https://github.com/max-sixty/worktrunk/blob/main/.config/wt.toml) for a complete example.
+See [Designing effective hooks](@/hook.md#designing-effective-hooks) for cross-platform CoW commands, language-specific tips, and more patterns.
## Dev server per worktree
diff --git a/src/cli.rs b/src/cli.rs
index dee5b1894..55a240a20 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1658,6 +1658,117 @@ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")
The JSON includes all template variables plus `hook_type` and `hook_name`.
+## Designing effective hooks
+
+### post-create vs post-start
+
+Both run when creating a worktree. The difference:
+
+| Hook | Execution | Best for |
+|------|-----------|----------|
+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |
+| `post-start` | Background, parallel | Long-running tasks that can finish while you work |
+
+Many tasks work well in `post-start` — they'll likely be ready by the time you need them, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.
+
+### Copying untracked files
+
+Git worktrees share the repository but not untracked files. Common files to copy or link:
+
+- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`
+- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`
+- **Generated assets**: Images, ML models, binaries too large for git
+- **Environment files**: `.env` (if not generated per-worktree)
+
+Three strategies:
+
+| Strategy | Speed | Disk | State |
+|----------|-------|------|-------|
+| **Symlink** | Instant | Shared | Shared (changes affect all worktrees) |
+| **Copy** | Slow | Full duplicate | Isolated |
+| **Copy-on-write** | Instant | Shared until modified | Isolated |
+
+### Copy-on-write for disk efficiency
+
+Copy-on-write (CoW) creates instant clones that share disk space until modified. Perfect for large directories.
+
+| OS | Filesystem | Command |
+|----|------------|---------|
+| macOS | APFS | `cp -c` |
+| Linux | Btrfs, XFS | `cp --reflink=auto` |
+| Windows | ReFS | No shell equivalent (requires API) |
+
+Cross-platform pattern that auto-detects and falls back gracefully:
+
+```toml
+[post-create]
+deps = """
+if cp -c /dev/null /dev/null 2>/dev/null; then
+ cp -c -r {{ repo_root }}/node_modules .
+elif cp --reflink=auto /dev/null /dev/null 2>/dev/null; then
+ cp --reflink=auto -r {{ repo_root }}/node_modules .
+else
+ cp -r {{ repo_root }}/node_modules .
+fi
+"""
+```
+
+### Dev servers
+
+Run a dev server per worktree on a deterministic port using `hash_port`:
+
+```toml
+[post-start]
+server = "npm run dev -- --port {{ branch | hash_port }}"
+```
+
+The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:
+
+```toml
+[list]
+url = "http://localhost:{{ branch | hash_port }}"
+```
+
+For subdomain-based routing (useful for cookies/CORS), use `lvh.me` which resolves to 127.0.0.1:
+
+```toml
+[post-start]
+server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+```
+
+### Databases
+
+Each worktree can have its own database. Docker containers get unique names and ports:
+
+```toml
+[post-start]
+db = """
+docker run -d --rm \
+ --name {{ repo }}-{{ branch | sanitize }}-postgres \
+ -p {{ 'db-' ~ branch | hash_port }}:5432 \
+ -e POSTGRES_DB={{ repo }} \
+ -e POSTGRES_PASSWORD=dev \
+ postgres:16
+"""
+
+[pre-remove]
+db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+```
+
+The `'db-' ~ branch` concatenation hashes differently than plain `branch`, so database and dev server ports don't collide.
+
+Generate `.env.local` with the connection string:
+
+```toml
+[post-create]
+env = """
+cat > .env.local << EOF
+DATABASE_URL=postgres://postgres:dev@localhost:{{ 'db-' ~ branch | hash_port }}/{{ repo }}
+DEV_PORT={{ branch | hash_port }}
+EOF
+"""
+```
+
## Security
Project commands require approval on first run:
@@ -1727,99 +1838,76 @@ if "gitlab" in ctx.get("remote", ""):
"""
```
-## Examples
+## Running hooks manually
-### Node.js / TypeScript
+`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
-```toml
-[post-create]
-install = "npm ci"
+```console
+wt hook pre-merge # Run all pre-merge hooks
+wt hook pre-merge test # Run hooks named "test" from both sources
+wt hook pre-merge user: # Run all user hooks
+wt hook pre-merge project: # Run all project hooks
+wt hook pre-merge user:test # Run only user's "test" hook
+wt hook pre-merge project:test # Run only project's "test" hook
+wt hook pre-merge --yes # Skip approval prompts (for CI)
+```
-[post-start]
-dev = "npm run dev"
+The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
-[pre-commit]
-lint = "npm run lint"
-typecheck = "npm run typecheck"
+## Language-specific tips
-[pre-merge]
-test = "npm test"
-build = "npm run build"
-```
+Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.
### Rust
-```toml
-[post-create]
-build = "cargo build"
+The `target/` directory is huge (often 1-10GB) and benefits most from CoW. Worktrunk's own config seeds compiled dependencies:
-[pre-commit]
-format = "cargo fmt -- --check"
-clippy = "cargo clippy -- -D warnings"
+```toml
+[post-start]
+deps = """
+[ -d {{ repo_root }}/target/debug/deps ] && [ ! -e target ] &&
+mkdir -p target/debug/deps &&
+cp -c {{ repo_root }}/target/debug/deps/*.rlib {{ repo_root }}/target/debug/deps/*.rmeta target/debug/deps/ &&
+cp -cR {{ repo_root }}/target/debug/.fingerprint {{ repo_root }}/target/debug/build target/debug/
+"""
+```
-[pre-merge]
-test = "cargo test"
-build = "cargo build --release"
+This cuts first build from ~68s to ~3s by reusing compiled dependencies. The check `[ ! -e target ]` skips if target already exists.
-[post-merge]
-install = "cargo install --path ."
-```
+### Python
-### Python (uv)
+Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:
```toml
[post-create]
install = "uv sync"
-
-[pre-commit]
-format = "uv run ruff format --check ."
-lint = "uv run ruff check ."
-
-[pre-merge]
-test = "uv run pytest"
-typecheck = "uv run mypy ."
```
-### Monorepo
+For pip-based projects without uv:
```toml
[post-create]
-frontend = "cd frontend && npm ci"
-backend = "cd backend && cargo build"
-
-[post-start]
-database = "docker-compose up -d postgres"
-
-[pre-merge]
-frontend-tests = "cd frontend && npm test"
-backend-tests = "cd backend && cargo test"
+venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"
```
-## Running hooks manually
+### Node.js
-`wt hook <type>` runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
+`node_modules/` is large but mostly static. CoW works well:
-```console
-wt hook pre-merge # Run all pre-merge hooks
-wt hook pre-merge test # Run hooks named "test" from both sources
-wt hook pre-merge user: # Run all user hooks
-wt hook pre-merge project: # Run all project hooks
-wt hook pre-merge user:test # Run only user's "test" hook
-wt hook pre-merge project:test # Run only project's "test" hook
-wt hook pre-merge --yes # Skip approval prompts (for CI)
+```toml
+[post-create]
+deps = "cp -c -r {{ repo_root }}/node_modules . 2>/dev/null || npm ci"
```
-The `user:` and `project:` prefixes filter by source. Use `user:` or `project:` alone to run all hooks from that source, or `user:name` / `project:name` to run a specific hook.
-
-### Common patterns
-
-**Fast dependencies + slow build** — Install blocking, build in background:
+If the project has no native dependencies, symlinks are even faster:
```toml
-post-create = "npm install"
-post-start = "npm run build"
+[post-create]
+deps = "ln -sf {{ repo_root }}/node_modules ."
```
+### Hook flow patterns
+
**Progressive validation** — Quick checks before commit, thorough validation before merge:
```toml
@@ -1832,7 +1920,7 @@ test = "npm test"
build = "npm run build"
```
-**Target-specific behavior**:
+**Target-specific behavior** — Different actions for production vs staging:
```toml
post-merge = """
@@ -1844,14 +1932,6 @@ fi
"""
```
-**Symlinks and caches** — The `{{ repo_root }}` variable points to the main worktree:
-
-```toml
-[post-create]
-cache = "ln -sf {{ repo_root }}/node_modules node_modules"
-env = "cp {{ repo_root }}/.env.local .env"
-```
-
## See also
- [wt merge](@/merge.md) — Runs hooks automatically during merge