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

Use sibling folders so each worktree is obvious:

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

Name the folder after the branch or task.

### 2. Create the worktree

```powershell
# Existing branch
git worktree add ..\repo-feature-api feature/api-contract

# New branch created from the current HEAD
git worktree add -b feature/perf-audit ..\repo-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 -> `..\repo-feature-api`
- Agent B -> `..\repo-perf-audit`
- Agent C -> `..\repo-docs-sync`

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

### 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:

```powershell
git worktree remove ..\repo-feature-api
git worktree prune
```

If uncommitted changes remain and removal is intentional:

```powershell
git worktree remove --force ..\repo-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.

```powershell
$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:

```text
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.
- 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

| Mistake | Fix |
|---------|-----|
| Reusing the same branch in multiple worktrees | Create a second branch or remove the first worktree |
| Forgetting which directory maps to which task | Name folders after the branch or task |
| Leaving stale worktree references behind | Run `git worktree prune` regularly |
| Treating worktrees like fully separate repositories | Remember git history and object storage are shared |
| Forcing cleanup on the wrong path | Check `git worktree list` and resolve the path before removal |

## 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
- [ ] Finished worktrees are removed and pruned
- [ ] Any forced cleanup path was verified against the registered worktree list

## Runtime Notes

### 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.

```text
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.

```json
{
  "worktree": {
    "baseRef": "fresh"
  }
}
```

| Value | Effect |
|-------|--------|
| `"fresh"` (default) | Start from the remote default branch baseline, so unpublished local commits are not carried into the new worktree |
| `"head"` | Start from the current local HEAD, so unpublished local commits are carried into the new worktree |

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`](../../copilot-exclusive/fleet-parallel/SKILL.md) — distribute independent work in parallel
- [`scope-guard`](../../copilot-exclusive/scope-guard/SKILL.md) — narrow writable scope inside a checkout or worktree
- [`github-pr-workflow`](../../copilot-exclusive/github-pr-workflow/SKILL.md) — move isolated branch work into PR flow
- [`commit-workflow`](../commit-workflow/SKILL.md) — keep each branch's commits clean and atomic