Worktrunk: parallel worktrees, lifecycle control and source analysis
Worktrunk quickstart: one disposable branch and a verifiable result
Learn the smallest worktree exercise, separate successful creation from shell navigation, and avoid accidental hooks or cleanup.
What you will learn
- Prepare a disposable learning environment
- Create once and verify two different outcomes
- Make completion observable before learning cleanup
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
- Use a disposable repository and disable lifecycle hooks for the first exercise.
- Worktree creation and parent-shell navigation are different checks.
- Do not use merge or force removal to finish a quickstart.
Prepare a disposable learning environment
Begin with a disposable repository containing an initial commit, a reviewed Worktrunk installation and a shell whose integration you understand. Inspect both user and project configuration before proceeding. Even a new repository can inherit user hooks; an unfamiliar checkout can contain .config/wt.toml. The installation chapter covers these configuration layers rather than asking you to paste a global setup command without context.
The first exercise deliberately excludes an agent, dependency installation and merge. On macOS or Linux the documented interface uses wt; on Windows use the direct git-wt command to avoid the Windows Terminal name collision. The sample below is an intended reader exercise, not a transcript of an execution we performed.
Create once and verify two different outcomes
In that disposable repository, wt switch --create demo-review --no-hooks requests a new branch and checkout without Worktrunk lifecycle hooks. Use the Windows command name where applicable. A successful creation message establishes neither that your parent shell changed directory nor that the new branch contains useful work. Check the current branch, current directory and Git worktree listing separately.
If the worktree appears in git worktree list --porcelain but your shell remains in the original directory, inspect shell integration rather than repeatedly creating the branch. The source distinguishes an installed wrapper from an active wrapper. Running an explicit binary path can bypass it, and git wt runs as a Git subprocess that cannot change its parent shell directory.
Make completion observable before learning cleanup
Your acceptance record should contain the original branch, new branch, new path and a clean status in the intended checkout. If the branch already exists, stop and inspect it instead of introducing a force flag. If creation fails, retain the error and original state; do not infer success from the presence of a partially created directory.
For this exercise, return to the original directory and leave the disposable checkout in place until you understand the removal chapter. Do not use wt merge as an exit command: its documented default can stage changes, squash, rebase and remove the source worktree. No merge or removal is needed to demonstrate that separate checkouts work.
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
Review configuration and record the original branch and path.
- 2
Create demo-review with lifecycle hooks disabled.
- 3
Inspect branch, path, status and the worktree listing.
- 4
Return to the original directory and defer cleanup.
Copy-ready example
# Reader exercise in a disposable, initialized repository only.
# Windows: use git-wt instead of wt.
wt switch --create demo-review --no-hooks
git branch --show-current
git status --short
git worktree list --porcelainFrequently asked questions
Why did the directory not change?
A missing or bypassed shell wrapper is one possibility; first verify whether worktree creation itself succeeded.
Does --no-hooks remove all risk?
No. It disables the supported Worktrunk hooks for this operation, not Git mutations or every process your environment can execute.
Sources
- Worktrunk / README.mdSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/hook.mdSource checked 2026-09-14
- Worktrunk / src/output/shell_integration.rsSource checked 2026-09-14