---
name: Using Git Worktrees
slug: using-git-worktrees-4
category: DevOps
description: Using Git Worktrees helps when a task needs a separate checkout, dirty state blocks branch switching, or the repository explicitly requires a worktree. It guides safe creation, placement, setup, and cleanup of task-owned worktrees.
github: "https://github.com/GanyuanRan/Aegis/tree/main/skills/using-git-worktrees"
language: Python
stars: 1086
forks: 50
install: "npx degit https://github.com/GanyuanRan/Aegis/tree/main/skills/using-git-worktrees ~/.claude/skills/using-git-worktrees"
installs_to: ~/.claude/skills/using-git-worktrees
source_path: skills/using-git-worktrees/SKILL.md
collection_size: 22
category_size: 798
collection_url: "https://dirskills.com/collections/GanyuanRan/Aegis"
added: 2026-08-21T05:13:24.502Z
last_synced: 2026-08-21T05:13:24.502Z
canonical_url: "https://dirskills.com/skills/using-git-worktrees-4"
---

# Using Git Worktrees

Using Git Worktrees helps when a task needs a separate checkout, dirty state blocks branch switching, or the repository explicitly requires a worktree. It guides safe creation, placement, setup, and cleanup of task-owned worktrees.

**Install:**

```bash
npx degit https://github.com/GanyuanRan/Aegis/tree/main/skills/using-git-worktrees ~/.claude/skills/using-git-worktrees
```

## README

# Using Git Worktrees

## Overview

A worktree is an exception for simultaneously checking out another Git history,
not a general safety badge. Prefer the current workspace and reuse an existing
suitable worktree. A branch decision and a worktree decision are separate.

**Core principle:** create only with necessity and ownership evidence; pair every
created worktree with a cleanup path.

**Announce at start:** explain which concrete checkout conflict requires a
worktree.

## Step 0: Environment Detection

Before mutation, record the repository root, `HEAD`, branch/detached state,
staged/unstaged/untracked paths, active Git operations, and:

```bash
git worktree list --porcelain
```

Stop on detached HEAD, unresolved conflicts, or an active merge/rebase/
cherry-pick/revert/bisect. Preserve user state: no automatic stash, reset,
clean, broad staging, or commit.

Before deciding necessity or placement, read the smallest relevant project
`AGENTS.md`, `CLAUDE.md`, current authority, and existing worktree convention.
Repository policy may require or forbid isolation and owns any approved
in-repo location; do not discover that policy after creating the checkout.

## Step 1: Necessity Decision

Create at most one task-owned worktree only when one of these is true:

- another branch must remain checked out while this task proceeds;
- unrelated dirty state prevents a safe checkout in the current workspace;
- explicit user or current repository authority requires it.

Task complexity, planning, TDD, use of subagents, or a `main`/`master` branch
name is not sufficient. Same-task subagents share one workspace; do not create
per-subagent or nested worktrees. If independent history is unnecessary, do not
create a branch either.

Record: reason, branch, exact path, creating coordinator, and expected cleanup
event. If the owner or cleanup condition is unknown, stop before creation.

## Step 2: Safe Placement

Use an existing repository convention only when the target directory is already
ignored (`git check-ignore`). Never edit or commit `.gitignore` solely to host a
worktree. If no safe in-repo convention exists, use a task-specific external
user-level temporary directory outside the repository. Resolve and verify the
exact path before creation; do not target a broad home, workspace, or repo root.

## Step 3: Create the Minimum Checkout

Prefer reusing an existing branch carrying the same goal. Create a branch only
when the approved Git lifecycle requires independent history.

```bash
# Existing branch
git worktree add <exact-path> <branch>

# New independently justified branch
git worktree add -b <branch> <exact-path> <start-point>
```

Read back `git worktree list --porcelain`, the new worktree's `HEAD`/branch, and
its status. Do not use force flags.

## Step 4: Authority-Led Setup and Baseline

Read the project's install docs, lockfiles, and existing setup scripts. Run
only setup the project explicitly requires. Do not infer `npm install`,
`cargo build`, `pip install`, `poetry install`, or dependency downloads merely
from manifest presence.

Run the smallest relevant baseline verification. If setup or tests fail, report
the exact failure and preserve the worktree; do not hide it by mutating unrelated
files.

## Step 5: Handoff and Cleanup Ownership

Report the exact path, branch, start `HEAD`, baseline result, owner, and cleanup
trigger. The creating coordinator remains responsible until it proves cleanup
or explicitly hands ownership off.

Use `finishing-a-development-branch` after the task commit or integration
decision. A worktree may usually be removed while its unmerged branch remains;
an open PR does not require a permanent checkout.

## Red Flags

Never:

- create a worktree only because a task modifies code;
- modify `.gitignore` merely to make worktree creation possible;
- install dependencies blindly;
- create one worktree per subagent;
- run global prune or force cleanup as routine hygiene;
- remove dirty, untracked, locked, user-owned, or ownership-unknown resources.

## Integration

Called conditionally by planning/execution workflows only after the necessity
decision. Pairs with `finishing-a-development-branch` for evidence-led cleanup.