Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Docs: Add dedicated Hooks page
Maximilian Roos0f101f27f689
diff --git a/docs/content/advanced.md b/docs/content/advanced.mdindex fb5771474..c1bedaf99 100644--- a/docs/content/advanced.md+++ b/docs/content/advanced.md@@ -1,6 +1,6 @@+++title = "Advanced Features"-weight = 7+weight = 8+++Most Worktrunk users get everything they need from `wt switch`, `wt list`, `wt merge`, and `wt remove`. The features below are optional power-user capabilities.diff --git a/docs/content/commands.md b/docs/content/commands.mdindex 8e6dabb11..996ae681c 100644--- a/docs/content/commands.md+++ b/docs/content/commands.md@@ -1,6 +1,6 @@+++title = "Commands Reference"-weight = 5+weight = 6+++## wt switchdiff --git a/docs/content/configuration.md b/docs/content/configuration.mdindex 4ca1fff01..0b4374e59 100644--- a/docs/content/configuration.md+++ b/docs/content/configuration.md@@ -3,9 +3,6 @@ title = "Configuration"weight = 4+++-<!-- TODO: This user config vs project config distinction is a good organizing- principle - consider orienting more of the docs around it -->-Worktrunk uses two configuration files:- **User config**: `~/.config/worktrunk/config.toml` — Personal settings, LLM commands, saved approvals@@ -13,69 +10,19 @@ Worktrunk uses two configuration files:## Project Hooks-Automate setup and validation at worktree lifecycle events:--| Hook | When | Example |-|------|------|---------|-| **post-create** | After worktree created | `cp -r .cache`, `ln -s` |-| **post-start** | After worktree created (background) | `npm install`, `cargo build` |-| **pre-commit** | Before creating any commit | `pre-commit run` |-| **pre-merge** | After squash, before push | `cargo test`, `pytest` |-| **post-merge** | After successful merge | `cargo install --path .` |+Create `.config/wt.toml` in your repository to automate setup and validation at worktree lifecycle events. See the dedicated [Hooks](/hooks/) page for complete documentation.-### Example project config--Create `.config/wt.toml` in your repository:+Quick example:```toml-# Install dependencies, build setup (blocking)[post-create]-"install" = "uv sync"--# Dev servers, file watchers (runs in background)-[post-start]-"dev" = "uv run dev"+install = "npm ci"-# Tests and lints before merging (blocks on failure)[pre-merge]-"lint" = "uv run ruff check"-"test" = "uv run pytest"--# After merge completes-[post-merge]-"install" = "cargo install --path ."+test = "npm test"+lint = "npm run lint"```-### Hook execution--<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_post_create.snap — edit source to update -->--{% terminal() %}-<span class="prompt">$</span> wt switch --create feature-x-🔄 <span style='color:var(--cyan,#0aa)'>Running post-create <b>install</b>:</span>-<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> sync</span>-- Resolved 24 packages in 145ms- Installed 24 packages in 1.2s-✅ <span style='color:var(--green,#0a0)'>Created new worktree for <b>feature-x</b> from <b>main</b> at <b>../repo.feature-x</b></span>-🔄 <span style='color:var(--cyan,#0aa)'>Running post-start <b>dev</b>:</span>-<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> run dev</span>-{% end %}--<!-- END AUTO-GENERATED -->--**Security**: Project commands require approval on first run. Approvals are saved to user config. Use `--force` to bypass prompts or `--no-verify` to skip hooks entirely.--### Template variables--Hooks can use these variables:--- `{{ repo }}` — Repository name-- `{{ branch }}` — Branch name-- `{{ worktree }}` — Worktree path-- `{{ repo_root }}` — Repository root path-- `{{ target }}` — Target branch (for merge hooks)-## LLM Commit MessagesWorktrunk can invoke external commands to generate commit messages. [llm](https://llm.datasette.io/) from Simon Willison is recommended.diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 879255617..610d01f1e 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -1,6 +1,6 @@+++title = "FAQ"-weight = 8+weight = 9+++## What commands does Worktrunk execute?diff --git a/docs/content/hooks.md b/docs/content/hooks.mdnew file mode 100644index 000000000..dd5e196db--- /dev/null+++ b/docs/content/hooks.md@@ -0,0 +1,377 @@+++++title = "Hooks"+weight = 5++++++Hooks automate setup and validation at worktree lifecycle events. They're defined in `.config/wt.toml` (project config) and run automatically during `wt switch --create` and `wt merge`.++## Hook Types++| Hook | When | Blocking? | Fail-Fast? | Execution |+|------|------|-----------|------------|-----------|+| **post-create** | After worktree created | Yes | No | Sequential |+| **post-start** | After worktree created | No | No | Parallel (background) |+| **pre-commit** | Before commit during merge | Yes | Yes | Sequential |+| **pre-merge** | Before merging to target | Yes | Yes | Sequential |+| **post-merge** | After successful merge | Yes | No | Sequential |++**Blocking**: Command waits for hook to complete before continuing.+**Fail-fast**: First failure aborts the operation.++## Configuration Formats++All hooks support three formats in `.config/wt.toml`:++### Single Command (String)++```toml+post-create = "npm install"+```++### Multiple Commands (Array)++```toml+post-create = ["npm install", "npm run build"]+```++### Named Commands (Table)++```toml+[post-create]+install = "npm install"+build = "npm run build"+```++Named commands appear in output with their labels:++<!-- ⚠️ AUTO-GENERATED-HTML from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_hooks_post_create.snap — edit source to update -->++{% terminal() %}+<span class="prompt">$</span> wt switch --create feature-x+🔄 <span style='color:var(--cyan,#0aa)'>Running post-create <b>install</b>:</span>+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> sync</span>++ Resolved 24 packages in 145ms+ Installed 24 packages in 1.2s+✅ <span style='color:var(--green,#0a0)'>Created new worktree for <b>feature-x</b> from <b>main</b> at <b>../repo.feature-x</b></span>+🔄 <span style='color:var(--cyan,#0aa)'>Running post-start <b>dev</b>:</span>+<span style='background:var(--bright-white,#fff)'> </span> <span style='opacity:0.67'><span style='color:var(--blue,#00a)'>uv</span></span><span style='opacity:0.67'> run dev</span>+{% end %}++<!-- END AUTO-GENERATED -->++## Template Variables++Hooks can use template variables that expand at runtime:++### Basic Variables (All Hooks)++- `{{ repo }}` — Repository name (e.g., "my-project")+- `{{ branch }}` — Branch name (slashes replaced with dashes)+- `{{ worktree }}` — Absolute path to the worktree+- `{{ repo_root }}` — Absolute path to the repository root++### Merge Variables (pre-commit, pre-merge, post-merge)++- `{{ target }}` — Target branch for the merge (e.g., "main")++```toml+pre-merge = "echo 'Merging {{ branch }} into {{ target }}'"+```++## Hook Details++### post-create++Runs after worktree creation, **blocks until complete**. The worktree switch doesn't finish until these commands succeed.++**Use cases**: Installing dependencies, database migrations, copying environment files — anything that must complete before work begins.++```toml+[post-create]+install = "npm ci"+migrate = "npm run db:migrate"+env = "cp .env.example .env"+```++**Behavior**:+- Commands run sequentially in declaration order+- Failure shows error but doesn't abort (worktree already created)+- User cannot work in worktree until complete++### post-start++Runs after worktree creation, **in background**. The worktree switch completes immediately; these run in parallel.++**Use cases**: Long builds, dev servers, file watchers — anything slow that doesn't need to block.++```toml+[post-start]+build = "npm run build"+server = "npm run dev"+```++**Behavior**:+- All commands start immediately in parallel+- Output logged to `.git/wt-logs/{branch}-post-start-{name}.log`+- Failures don't affect the user session++### pre-commit++Runs before committing during `wt merge`, **fail-fast**. All commands must exit with code 0 for the commit to proceed.++**Use cases**: Formatters, linters, type checking — quick validation before commit.++```toml+[pre-commit]+format = "cargo fmt -- --check"+lint = "cargo clippy -- -D warnings"+```++**Behavior**:+- Commands run sequentially+- First failure aborts the commit+- Runs for both squash and no-squash merge modes++### pre-merge++Runs before merging to target branch, **fail-fast**. All commands must exit with code 0 for the merge to proceed.++**Use cases**: Tests, security scans, build verification — thorough validation before merge.++```toml+[pre-merge]+test = "cargo test"+build = "cargo build --release"+```++**Behavior**:+- Commands run sequentially+- First failure aborts the merge (commit remains)+- Runs after commit succeeds, before merge++### post-merge++Runs after successful merge, **best-effort**. The merge has already completed, so failures are logged but don't abort.++**Use cases**: Deployment, notifications, installing updated binaries — post-merge automation.++```toml+post-merge = "cargo install --path ."+```++**Behavior**:+- Commands run sequentially in the **main worktree** (not feature branch)+- Runs after push succeeds, before cleanup+- Failures show errors but cleanup proceeds++## Execution Order During Merge++The complete sequence when running `wt merge`:++1. Validate working tree is clean+2. **Run `pre-commit`** — fail-fast, aborts if any command fails+3. Create commit (with LLM message if configured)+4. Switch to main worktree+5. Pull latest changes+6. **Run `pre-merge`** — fail-fast, aborts if any command fails+7. Merge branch into target+8. Push to remote+9. **Run `post-merge`** — best-effort, failures logged+10. Clean up (delete branch, remove worktree)++## Security & Approval++Project commands require approval on first run. When a project defines hooks, the first execution prompts for approval:++<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->++```+🟡 repo needs approval to execute 3 commands:++⚪ post-create install:+ echo 'Installing dependencies...'++⚪ post-create build:+ echo 'Building project...'++⚪ post-create test:+ echo 'Running tests...'++💡 Allow and remember? [y/N]+```++<!-- END AUTO-GENERATED -->++**Approval behavior**:+- Approvals are saved to user config (`~/.config/worktrunk/config.toml`)+- If a command changes, new approval is required+- Use `--force` to bypass prompts (useful for CI/automation)++Manage approvals with `wt config approvals`:++```bash+wt config approvals list # Show all approvals+wt config approvals clear <repo> # Remove approvals for a repo+```++## Skipping Hooks++Use `--no-verify` to skip all project hooks:++```bash+wt switch --create temp --no-verify # Skip post-create and post-start+wt merge --no-verify # Skip pre-commit, pre-merge, post-merge+```++## Logging++Background operations log to `.git/wt-logs/` in the main worktree:++| Operation | Log file |+|-----------|----------|+| post-start | `{branch}-post-start-{name}.log` |+| Background removal | `{branch}-remove.log` |++Logs overwrite on repeated runs for the same branch/operation. Stale logs from deleted branches persist but are bounded by branch count.++## Running Hooks Manually++Use `wt step` to run individual hooks:++```bash+wt step post-create # Run post-create hooks+wt step pre-merge # Run pre-merge hooks+wt step post-merge # Run post-merge hooks+```++## Example Configurations++### Node.js / TypeScript++```toml+[post-create]+install = "npm ci"++[post-start]+dev = "npm run dev"++[pre-commit]+lint = "npm run lint"+typecheck = "npm run typecheck"++[pre-merge]+test = "npm test"+build = "npm run build"+```++### Rust++```toml+[post-create]+build = "cargo build"++[pre-commit]+format = "cargo fmt -- --check"+clippy = "cargo clippy -- -D warnings"++[pre-merge]+test = "cargo test"+build = "cargo build --release"++[post-merge]+install = "cargo install --path ."+```++### Python (uv)++```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 ."+```++### Python (pip/venv)++```toml+[post-create]+venv = "python -m venv .venv"+install = ".venv/bin/pip install -r requirements.txt"++[pre-merge]+format = ".venv/bin/black --check ."+lint = ".venv/bin/ruff check ."+test = ".venv/bin/pytest"+```++### Monorepo++```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"+integration = "./scripts/integration-tests.sh"+```++## Common Patterns++### Fast Dependencies + Slow Build++Install dependencies blocking (must complete before work), build in background:++```toml+post-create = "npm install"+post-start = "npm run build"+```++### 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 behavior based on merge target:++```toml+post-merge = """+if [ "{{ target }}" = "main" ]; then+ npm run deploy:production+elif [ "{{ target }}" = "staging" ]; then+ npm run deploy:staging+fi+"""+```++### Symlinks and Caches++Set up shared resources that shouldn't be duplicated:++```toml+[post-create]+cache = "ln -sf ../main-worktree/node_modules node_modules"+env = "cp ../.env.local .env"+```diff --git a/docs/content/quickstart.md b/docs/content/quickstart.mdindex aadb97f75..04ae0d260 100644--- a/docs/content/quickstart.md+++ b/docs/content/quickstart.md@@ -82,5 +82,5 @@ Worktrunk checks if your changes are already on main before deleting the branch.## Next steps- Understand [why worktrees matter](/concepts/) and how Worktrunk improves on plain git-- Set up [project hooks](/configuration/) for automated setup+- Set up [project hooks](/hooks/) for automated setup- Use [LLM commit messages](/configuration/#llm-commit-messages) for auto-generated commitsdiff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 0434dada8..c72d396cd 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -1,6 +1,6 @@+++title = "Tips & Patterns"-weight = 6+weight = 7+++Practical recipes for common Worktrunk workflows.