Skip to content

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.md
index 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.toml
index 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