using-git-worktrees

Using Git Worktrees

Git worktrees let one repository have multiple active working directories. Use them when parallel tasks should not compete for the same checkout.

When to Use

• Parallel agent or human work on separate branches
• Reviewing or hotfixing another branch without stashing current work
• Waiting on CI or review for one branch while continuing on another
• Running long-lived experiments that should stay isolated from the main checkout

When NOT to Use

Instead of using-git-worktrees	Use
A single quick change on the current branch	stay in the current checkout
Two subtasks that must edit the same files together	one branch, one worktree
Disposable experimentation with no branch history needed	a temporary local branch may be enough

Workflow

1. Pick a directory layout

Option A — Sibling folders (traditional): each worktree is a sibling of the main repo:

C:\work\repo-main
C:\work\repo-feature-api
C:\work\repo-feature-docs

Option B — Project-internal .worktrees/ directory (recommended for Copilot CLI agent workflows): Keep all worktrees inside the project root for easier discovery and cleaner orchestration briefs:

C:\work\repo-main
C:\work\repo-main\.worktrees\feature-api
C:\work\repo-main\.worktrees\feature-docs

Advantages of project-internal layout:

• All active worktrees visible from one root path — no guessing sibling names
• Agents receive a relative path (.\\.worktrees\\feature-api) instead of an absolute sibling path
• Easier to clean up: removing the project removes all its worktrees
• Git-ignore .worktrees/ to prevent accidental tracking of worktree state files

# Create a project-internal worktree
git worktree add .worktrees\feature-api feature/api-contract

# Or from the project root
git worktree add .\.worktrees\perf-audit -b feature/perf-audit

# List
git worktree list

Add .worktrees/ to .gitignore to prevent worktree bookkeeping files from being committed: