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

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:

# .gitignore
.worktrees/

Name the folder after the branch or task.

2. Create the worktree

# Existing branch (sibling layout)
git worktree add ..\repo-feature-api feature/api-contract

# Existing branch (project-internal layout)
git worktree add .worktrees\feature-api feature/api-contract

# New branch created from the current HEAD
git worktree add -b feature/perf-audit .worktrees\perf-audit

# Inspect active worktrees
git worktree list

Each worktree gets its own working directory while sharing the same repository object database.

3. Assign one worktree per task

Use a dedicated branch and directory for each independent task:

• Agent A -> .worktrees\feature-api
• Agent B -> .worktrees\perf-audit
• Agent C -> .worktrees\docs-sync

Do not send two independent agents into the same worktree. That defeats the isolation.

After assigning a subagent to a worktree, verify its actual Git execution context instead of assuming path-passing was enough. Have the subagent run git rev-parse --show-toplevel (or run git -C <worktree> rev-parse --show-toplevel yourself) and confirm it resolves to the assigned worktree path, not the main/shared checkout.

4. Keep branch ownership clear

• One worktree per checked-out branch
• One main task per worktree
• Clear branch names (feature/*, fix/*, docs/*)
• Keep a short note on what each worktree is for

If the task also uses fleet or background agents, pass the exact worktree path in the brief.

5. Merge and clean up

After the branch is merged or no longer needed:

# Sibling layout
git worktree remove ..\repo-feature-api

# Project-internal layout
git worktree remove .worktrees\feature-api

git worktree prune

If uncommitted changes remain and removal is intentional:

git worktree remove --force .worktrees\feature-api
git worktree prune

Before any forced cleanup, verify that the target path is a real worktree path from git worktree list. Do not pass an unchecked or hand-typed path straight into force removal.

$target = Resolve-Path ..\repo-feature-api
$known = git worktree list --porcelain |
  Select-String '^worktree ' |
  ForEach-Object { $_.ToString().Substring(9) }

if ($target.Path -notin $known) {
    throw "Refusing cleanup: path is not a registered git worktree"
}

For Copilot Orchestrators: Direct Agents into the Right Worktree

Copilot CLI does not expose a dedicated EnterWorktree tool. The safe equivalent is to put the agent in the correct checkout up front and restate that boundary in the brief.

Use a prompt that names the exact worktree path and forbids edits in the main checkout:

Work only in C:\work\repo-feature-api.
Treat that worktree as your writable surface.
Read the main checkout for reference if needed, but do not edit, create, or delete files there.

Operational rules:

• Launch each background or delegated agent from the intended worktree, or give it commands that explicitly Set-Location into that path before it edits anything.
• After handoff, confirm the agent's Git commands resolve to that same worktree path with git rev-parse --show-toplevel before trusting branch or status output.
• Keep one active branch and one primary owner per worktree.
• If multiple agents need different branches, create multiple worktrees rather than sharing one.
• Pair this with a narrow file brief when the worktree still contains too much writable surface.
• Verify the branch and path pairing before destructive cleanup or recreation.

Windows Tips

• Prefer relative sibling paths like ..\repo-feature-api
• Keep names short enough to avoid deep path problems
• If tooling caches absolute paths, run setup once per worktree
• Each worktree needs its own untracked build artifacts and environment state
• If a worktree stores shared notes or copied logs, scrub secrets and tokens before committing them

Common Mistakes

Verification

• Each parallel task has its own directory and branch
• No two active tasks are editing through the same worktree
• git worktree list shows the expected layout
• Each subagent's git rev-parse --show-toplevel resolves to its assigned worktree, not the shared checkout
• Finished worktrees are removed and pruned
• Any forced cleanup path was verified against the registered worktree list

Runtime Notes

GitHub Copilot CLI: Experimental Worktree Entry Points

Copilot CLI's worktree feature is experimental and provides these entry points:

/worktree, /worktree new, and --worktree branch from the current checkout (HEAD) by default. This became consistent in CLI v1.0.79; previously, --worktree started from the remote default branch. To retain that older baseline intentionally, set worktreeBaseRef to "defaultBranch" so new worktrees branch from the remote default branch instead. The reference does not document worktreeBaseRef for /move.

--worktree conflicts with --resume, --continue, and --connect; do not combine those flags. Use these entry points when creation inside the session is the desired operation. For an existing checkout, keep using the explicit path-boundary flow in For Copilot Orchestrators. The Git-native git worktree add workflow remains the stable default.

Claude Code: Enter an Existing Worktree

Claude Code v2.1.105+ exposes EnterWorktree(path) for switching into an existing worktree of the current repository.

Use it after the orchestrator or human has already created the worktree with git worktree add. Keep worktree creation and cleanup Git-native; use EnterWorktree only to place a Claude subagent inside the correct checkout.

EnterWorktree(path: "/path/to/existing-worktree")

Pattern:

1. Create the worktree with git worktree add
2. Pass the exact worktree path to the subagent
3. Enter that checkout with EnterWorktree
4. Keep one subagent per worktree

Claude Code only: worktree.baseRef when Claude creates the worktree

Claude Code v2.1.133+ also supports a worktree.baseRef setting that affects Claude-created worktrees. This setting matters only when Claude is creating the worktree for a subagent; it does not change the recommended flow in this skill, where you create the worktree yourself with git worktree add and then enter it explicitly.

{
  "worktree": {
    "baseRef": "fresh"
  }
}

Use "head" only when the subagent must inherit local, unpushed commits. For the Git-native workflow in this skill (git worktree add first), this setting is usually not needed.

See Also

• fleet-parallel — distribute independent work in parallel
• scope-guard — narrow writable scope inside a checkout or worktree
• github-pr-workflow — move isolated branch work into PR flow
• commit-workflow — keep each branch's commits clean and atomic