Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Docs: Clarify hook execution and add config examples
Maximilian Roos400b0f50202a
diff --git a/README.md b/README.mdindex 62c7ca18e..e4d95e77d 100644--- a/README.md+++ b/README.md@@ -145,11 +145,16 @@ Projects can define commands that run automatically when creating or switching t**Hook Types:**-- **`post-create-command`**: Runs sequentially after creating a worktree. Use for setup tasks like installing dependencies.-- **`post-start-command`**: Runs in parallel as background processes after switching to a worktree. Use for dev servers and watchers.+- **`post-create-command`**: Runs **sequentially** and **blocks** until complete after creating a worktree. The `wt switch` command won't return until these finish. Use for essential setup tasks like installing dependencies or building assets. Commands execute one after another in the new worktree directory.++- **`post-start-command`**: Runs in **parallel** as **background processes** (non-blocking) after switching to a worktree. The `wt switch` command returns immediately while these run in the background. Use for dev servers, file watchers, and other long-running tasks. Output is logged to `~/.cache/worktrunk/logs/{repo}/{branch}/{command}.log`.+- **`pre-merge-command`**: Runs first, before any other hooks or git operations during `wt merge`. All commands must succeed for the merge to proceed. Use for validation (tests, lints) that must pass regardless of merge strategy.+- **`pre-commit-command`**: Runs after pre-merge but before committing uncommitted changes (when not using `--squash`). All commands must succeed for the commit to proceed. Use for format checks and quick validations.+- **`pre-squash-command`**: Runs after pre-merge but before squashing commits (when using `--squash`). All commands must succeed for the squash to proceed. Use for tests that should pass before creating the final squashed commit.+- **`post-merge-command`**: Runs sequentially in the main worktree after a successful merge and push. Use for deployment, notifications, or updating global state.Template variables expand at runtime:diff --git a/config.example.toml b/config.example.tomlindex 64d9cbfa2..b19df9953 100644--- a/config.example.toml+++ b/config.example.toml@@ -92,6 +92,30 @@ worktree-path = "../{main-worktree}.{branch}"# Supports ~ expansion: ~/.config/worktrunk/squash-template.txt# squash-template-file = "~/.config/worktrunk/squash-template.txt"+# Project Commands (Optional)+# Define commands that run automatically when creating/switching worktrees+# Place in `.config/wt.toml` in your repository root+#+# post-create-command: Runs SEQUENTIALLY and BLOCKS until complete+# - Use for: npm install, bundle install, build, essential setup+# - The worktree switch won't complete until these finish+# - Commands run one after another in the worktree directory+# - Example:+# [project.post-create-command]+# "install" = "npm install --frozen-lockfile"+# "build" = "npm run build"+#+# post-start-command: Runs in BACKGROUND as detached processes+# - Use for: dev servers, file watchers, long-running tasks+# - The worktree switch completes immediately, these run in parallel+# - Output is logged to ~/.cache/worktrunk/logs/{repo}/{branch}/{command}.log+# - Example:+# [project.post-start-command]+# "server" = "npm run dev"+# "watch" = "npm run watch"+#+# See README.md for complete documentation on all hook types+# Approved Commands# Commands approved for automatic execution after switching worktrees# Auto-populated when you use: wt switch --execute "command" --force