Git worktrees - Lesson 5 of 5

Run a complete parallel-work cycle

Use worktrees to keep two bounded tasks moving without hiding one task in a stash or contaminating the branch you are about to integrate.

Time: 15 minutesPrevious: maintainReference: field guide

The two-task layout

repo/                 # main integration checkout
repo-docs/            # docs/readme-refresh
repo-tests/           # test/login-errors

Use one branch and one directory per independently reviewable task. If two changes must land atomically, keep them in one task branch instead of pretending they are parallel.

Runbook

  1. Prepare the base

    In repo/, confirm a clean status, switch to the intended base, and update it according to team policy.

    git status --short
    git switch main
    git pull --ff-only

  2. Create bounded task worktrees

    git worktree add -b docs/readme-refresh ../repo-docs
    git worktree add -b test/login-errors ../repo-tests

    Confirm both paths and branches with git worktree list --verbose.

  3. Work and commit independently

    In each task directory, make a small change, inspect status and diff, run task-relevant checks, then commit. Do not leave work only as a dirty tree if you intend to switch context.

  4. Integrate one finished task

    Return to repo/, verify it is clean, merge or cherry-pick the selected work, then run the checks for the resulting target branch.

  5. Close only after verification

    git worktree remove ../repo-docs
    git branch -d docs/readme-refresh

    Keep repo-tests/ intact until its task is separately ready.

Completion card

Base branch and commit:
Task branch and worktree path:
Task-level checks run:
Commits to integrate:
Integration method and target:
Target-level checks run:
Worktree status before removal:
Cleanup command:
Remaining worktrees:
Decision rule: a task is not complete when its directory looks done. It is complete when its commits are safely integrated or intentionally preserved, the target is verified, and cleanup does not discard anything valuable.

Final retrieval check

Primary reading

Ask follow-up questions: Submit a completed card or your planned commands to the agent before applying this workflow in a shared production repository.