# Using Git Worktrees

> Create or verify an isolated git worktree before starting any development work. Prevents main branch contamination, enables parallel feature development, and gives subagents a clean baseline. Use at the start of every feature branch.

- **Type:** Skill
- **Install:** `agentstack add skill-rbraga01-a-team-using-git-worktrees`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RBraga01](https://agentstack.voostack.com/s/rbraga01)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [RBraga01](https://github.com/RBraga01)
- **Source:** https://github.com/RBraga01/a-team/tree/main/skills/using-git-worktrees
- **Website:** https://rbraga01.github.io/a-team/

## Install

```sh
agentstack add skill-rbraga01-a-team-using-git-worktrees
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Using Git Worktrees

## Why Worktrees

A worktree is a second checkout of the same repo in a separate directory. Each worktree has its own working tree and HEAD, but shares the git object store. This means:

- Subagents work in isolation — no interference with your main session
- You can switch tasks without stashing
- Parallel features develop independently
- Clean rollback: abandon the worktree, nothing pollutes main

## When to Use

Use at the START of every feature or bug fix. Do NOT start implementation until a clean worktree exists or you've confirmed you're already in one.

Mandatory before:
- `subagent-driven-development` skill
- `executing-plans` skill
- Any work touching more than one file

## The Process

### Step 1: Detect Existing Isolation

First check — are you already isolated?

```bash
# Check if current directory is a worktree (not the main checkout)
git worktree list
pwd
```

If you're already in a worktree for this feature: proceed to Step 3 (verify clean baseline).
If you're in the main checkout: proceed to Step 2.

### Step 2: Create the Worktree

```bash
# Create worktree + new branch in one command
git worktree add ../worktrees/ -b feat/

# Examples:
git worktree add ../worktrees/stripe-billing -b feat/stripe-billing
git worktree add ../worktrees/fix-auth-bug -b fix/auth-token-expiry
```

The worktree is created at `../worktrees/` (sibling of the project root).
If the project uses `.claude/worktrees/`, use that path instead:

```bash
git worktree add .claude/worktrees/ -b feat/
```

### Step 3: Verify Clean Baseline

Move into the worktree and confirm it starts clean:

```bash
cd ../worktrees/   # or .claude/worktrees/
git status                        # Should show: "nothing to commit"
git log --oneline -3              # Confirm you branched from the right point
```

If status shows unexpected changes: something is wrong — investigate before proceeding.

### Step 4: Run Project Setup

Install dependencies and confirm the baseline builds:

```bash
npm install          # or pip install -r requirements.txt / go mod download
npm run build        # Confirm baseline build passes BEFORE any changes
npm test             # Confirm baseline tests pass BEFORE any changes
```

If baseline build or tests fail: STOP. Fix the issue on main first, then recreate the worktree.

### Step 5: Proceed with Work

Now development starts. The worktree is isolated, the baseline is confirmed clean.

## Cleanup After Work Completes

After the branch is merged or abandoned:

```bash
# From the main checkout (not from inside the worktree)
git worktree remove ../worktrees/
git branch -d feat/   # Only after merge
```

## Common Issues

| Issue | Fix |
|-------|-----|
| "already checked out" error | The branch exists in another worktree — use a different branch name |
| Worktree has unexpected changes | Run `git status` to investigate; never force-remove with uncommitted work |
| Setup script fails in worktree | Check for absolute paths in scripts; worktrees use different working directories |
| Submodules not initialized | Run `git submodule update --init --recursive` in the new worktree |

## Worktree vs Branch Checkout

| | `git worktree` | `git checkout -b` |
|--|----------------|-------------------|
| Main session disrupted | No | Yes |
| Parallel work possible | Yes | No |
| Independent node_modules | Yes (separate dir) | Shared |
| Subagent isolation | Clean | Risk of contamination |

Always use worktrees for subagent work. The isolation is the point.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RBraga01](https://github.com/RBraga01)
- **Source:** [RBraga01/a-team](https://github.com/RBraga01/a-team)
- **License:** MIT
- **Homepage:** https://rbraga01.github.io/a-team/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-rbraga01-a-team-using-git-worktrees
- Seller: https://agentstack.voostack.com/s/rbraga01
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.