# Using Git Worktrees

> Make sure work happens in an isolated workspace before a feature or plan. A feature branch is the default and is enough for most work; reach for a worktree only when you need a second checkout at once (parallel agents, comparing branches, long build running). Detects existing isolation, prefers the harness's native worktree tool, falls back to git, verifies a clean baseline.

- **Type:** Skill
- **Install:** `agentstack add skill-hdprajwal-agent-skills-using-git-worktrees`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hdprajwal](https://agentstack.voostack.com/s/hdprajwal)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hdprajwal](https://github.com/hdprajwal)
- **Source:** https://github.com/hdprajwal/agent-skills/tree/main/skills/using-git-worktrees

## Install

```sh
agentstack add skill-hdprajwal-agent-skills-using-git-worktrees
```

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

## About

# Isolated Workspaces (Branches & Worktrees)

Work should never land directly on `main`. The default is a **feature branch** —
that's what fits the usual loop (branch → fix → PR → merge → delete →
next). A **worktree** is for when you genuinely need two checkouts at once:
running parallel agents on independent tasks, comparing branches side by side, or
keeping a long build/test going while you work elsewhere. If you don't need a
second checkout, a branch is simpler — don't over-engineer it.

**Say at the start:** "Setting up an isolated workspace."

## Branch (default)

```bash
git switch -c      # never start on main/master
```

That's it for most work. Skip the rest unless you actually need a second
checkout.

## Worktree (when you need a second checkout)

### Step 0 — detect existing isolation

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
```

`GIT_DIR != GIT_COMMON` is also true inside a submodule, so guard:

```bash
git rev-parse --show-superproject-working-tree 2>/dev/null  # path = submodule
```

- **`GIT_DIR != GIT_COMMON`, not a submodule:** already in a worktree — skip to
  Setup. Don't nest another.
- **Otherwise:** normal checkout. If the user hasn't stated a preference, ask
  before creating one.

### Step 1 — create it

**Native tool first.** If the harness has a worktree tool (something like
`EnterWorktree`, a `/worktree` command, or a `--worktree` flag), use it — it
handles placement, branch, and cleanup, and the harness can track it. Using
`git worktree add` when a native tool exists creates phantom state it can't see.

**Git fallback** (only if no native tool). Default dir `.worktrees/` (else
`worktrees/`; if both, `.worktrees/`). Project-local dirs MUST be git-ignored
first or their contents get committed:

```bash
git check-ignore -q .worktrees || { echo ".worktrees/" >> .gitignore && git add .gitignore && git commit -m "chore: ignore worktrees"; }
git worktree add ".worktrees/" -b ""
cd ".worktrees/"
```

If `git worktree add` fails on a sandbox permission error, tell the user and
work in place.

## Setup

Auto-detect and run:

```bash
[ -f pnpm-lock.yaml ]   && pnpm install
[ -f package.json ]     && [ ! -f pnpm-lock.yaml ] && npm install
[ -f Cargo.toml ]       && cargo build
[ -f go.mod ]           && go mod download
[ -f pyproject.toml ]   && (poetry install || pip install -e .)
```

## Verify a clean baseline

Run the test command (`pnpm test` / `cargo test` / `go test ./...`).

- **Fail:** report and ask whether to proceed — otherwise you can't tell new bugs
  from pre-existing ones.
- **Pass:** report ready.

## Never

- Start work on `main`/`master`.
- Spin up a worktree when a branch is all you need.
- Use `git worktree add` when a native worktree tool exists.
- Create a project-local worktree without verifying it's ignored.
- Skip the baseline test, or push through failures without asking.

## Source & license

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

- **Author:** [hdprajwal](https://github.com/hdprajwal)
- **Source:** [hdprajwal/agent-skills](https://github.com/hdprajwal/agent-skills)
- **License:** MIT

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-hdprajwal-agent-skills-using-git-worktrees
- Seller: https://agentstack.voostack.com/s/hdprajwal
- 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%.