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.mdindex 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+"""+```+## SecurityProject 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:```tomlpost-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 mergediff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 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 worktreediff --git a/src/cli.rs b/src/cli.rsindex 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+"""+```+## SecurityProject 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:```tomlpost-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