Worktrees
Guide for managing git worktrees in pokayokay.
When Worktrees Are Created
| Task Type | Default | Override |
|---|---|---|
| feature | Worktree | --in-place |
| bug | Worktree | --in-place |
| spike | Worktree | --in-place |
| chore | In-place | --worktree |
| docs | In-place | --worktree |
| test | Inherits | explicit flag |
Key Principles
- Story-based reuse — Tasks in the same story share a worktree for related changes
- Auto dependency install — Dependencies install automatically on worktree creation
- Clean completion — Choose merge, PR, keep, or discard when done
- Isolation — All worktrees live in
.worktrees/(auto-ignored by git)
Quick Start Checklist
- Task type determines worktree vs in-place (see table above)
- Story worktrees are reused across related tasks
- Dependencies auto-install based on detected lockfiles
- On completion: merge to main, create PR, keep, or discard
- Troubleshoot with
git worktree listif issues arise
References
| Reference | Description |
|---|---|
| worktree-management.md | Lifecycle, completion options, dependency install, troubleshooting |
| cleanup-strategies.md | Cleanup criteria, detection, disk management, scheduled cleanup |
| parallel-worktrees.md | Parallel execution worktree isolation, conflict prevention |