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 list if 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