Worktrunk: parallel worktrees, lifecycle control and source analysis
Worktrunk architecture: configuration, approvals and hook ordering
Trace control from an operation through configured commands, approval and pre/post hooks, including startup dependencies and merge behavior.
What you will learn
- Configuration supplies behavior, not just display preferences
- Pre and post hooks impose different dependency rules
- Merge is a lifecycle pipeline, not a synonym for Git merge
Before you start
- Basic Git branches and command-line navigation
- A disposable repository for optional reader exercises
Explain worktree boundaries, verify a first checkout and review configured commands before adopting automation.
Key takeaways
- Track Git mutations separately from hook outcomes.
- Use a blocking stage for prerequisites, not concurrent background tasks.
- A late failure does not imply earlier merge stages were rolled back.
Configuration supplies behavior, not just display preferences
A Worktrunk operation combines CLI intent with configuration. A worktree path template determines placement; hooks attach shell commands to lifecycle events. User settings and shared project configuration have different trust assumptions. A project can distribute a command template, but a local approval decision determines whether the project command may run in the inspected approval path.
Think of the architecture as two interacting flows: Git state changes and external command execution. A successful checkout can coexist with a later background hook failure. A denied project command does not necessarily cancel the entire worktree operation. Keeping these flows separate makes logs and failure messages much easier to interpret.
Pre and post hooks impose different dependency rules
The hook documentation describes pre hooks as blocking: a failure aborts the operation at that point. Post hooks normally run in the background with logs. For startup, pre-start completes before post-start and the requested --execute command. If a task needs installed dependencies, placing installation in a parallel post-start task can create a race; put the prerequisite in the documented blocking stage or explicit pipeline.
A string describes one command, a table groups concurrent commands, and a hook pipeline sequences steps while allowing commands within a step to run together. User pre hooks precede project pre hooks; post sources run independently. Do not assume source order serializes two background commands touching the same file, database or Git state.
Merge is a lifecycle pipeline, not a synonym for Git merge
The pinned merge documentation describes a workflow that can commit or squash, rebase, run pre-merge checks, advance a local target and then clean up. Unlike git merge, wt merge integrates the current branch into the target. It never fetches, so remote synchronization is a separate concern. Default staging can include all working-tree changes; review the diff before considering the operation.
A failure is not a transaction rollback. A rebase conflict can leave a rebase open, and a pre-remove failure occurs after the merge stage. Inspect the target ref and current state before retrying. Post-merge and post-remove work occurs after cleanup; these hooks should not assume the originating directory still exists. This chapter explains the documented sequence, not an executed merge experiment.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
List every configured lifecycle command.
- 2
Mark its source, approval requirement and blocking behavior.
- 3
Draw prerequisites before assigning concurrent steps.
- 4
Specify a recovery check for each mutating stage.
Copy-ready example
# Illustrative project configuration; not executed in this review.
# Sequential steps, with commands within each step concurrent.
[[pre-merge]]
test = "cargo test"
[[pre-merge]]
lint = "cargo clippy"Frequently asked questions
Does every hook failure cancel all previous work?
No. Failure stops at a stage; earlier mutations may already have happened.
Does wt merge fetch the newest remote branch?
The pinned documentation says it does not fetch. Remote synchronization must be handled separately.
Sources
- Worktrunk / docs/src/content/docs/config.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/hook.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/merge.mdSource checked 2026-09-14
- Worktrunk / src/commands/command_approval.rsSource checked 2026-09-14