# Using GIT Worktrees

Use when a coding task needs a concurrent checkout, unrelated dirty state blocks safe...

- Repository: https://github.com/GanyuanRan/Aegis (1408 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-25
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add GanyuanRan/Aegis --skill using-git-worktrees -g -a claude-code -y`
Codex: `npx skills add GanyuanRan/Aegis --skill using-git-worktrees -g -a codex -y`
Cursor: `npx skills add GanyuanRan/Aegis --skill using-git-worktrees -g -a cursor -y`
Gemini CLI: `npx skills add GanyuanRan/Aegis --skill using-git-worktrees -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add GanyuanRan/Aegis`

## Description

Use when a coding task needs a concurrent checkout, unrelated dirty state blocks safe branch switching, or the user or repository explicitly requires a worktree.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

Classify the current host surface's task/chat-bound managed workspace semantics
as `managed`, `non-managed`, or `unknown`. Use trusted host/session context, an
explicit host contract, or a host-native lifecycle result; do not infer the
classification from a product name, directory prefix, command-level `workdir`,
missing tool, or absent metadata. `non-managed` requires positive evidence that
the current surface lacks task-bound managed semantics. When the host exposes
workspace fields, record the task workspace and the command's default `cwd`
without a per-command directory override.

Stop on unresolved conflicts, an active merge/rebase/cherry-pick/revert/bisect,
or an unexplained detached HEAD. A detached HEAD is acceptable only when
trusted host binding evidence identifies it as the intended state of the
current managed worktree; Codex-managed worktrees, for example, start detached
by default. 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.

The rest: https://github.com/GanyuanRan/Aegis/blob/HEAD/skills/using-git-worktrees/SKILL.md