# Using Git Worktrees

> Creates isolated git worktrees for parallel development. Use when starting feature work needing isolation or working on multiple branches simultaneously. NOT for simple branch switching, bulk branch cleanup (use cleanup-git), or git hook/config setup (use configuring-git-hygiene).

- Skill: `alexei-led/using-git-worktrees` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add alexei-led/using-git-worktrees`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexei-led/using-git-worktrees/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexei-led (https://skillmd.com/u/alexei-led)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/alexei-led/using-git-worktrees

---


# Git Worktrees

Use one sibling worktree root per project: `<project>.worktrees/<branch-slug>`. Keep the main worktree clean on the integration branch by default. Trivial solo one-liners may stay in the main worktree when a worktree would add pointless ceremony.

Treat a worktree as a disposable branch folder. Remove it and its branch after the PR merges.

## Scope

Use this skill when:

- starting a feature, fix, or experiment that should not disturb current work
- working on multiple branches at once
- trying competing approaches
- the current worktree has uncommitted changes and the user wants to start something else

Do not use this skill for:

- simple branch switching with no parallel work
- bulk branch or stale worktree cleanup — use `cleanup-git`
- git hook, Gitleaks, `.gitignore`, or config setup — use `configuring-git-hygiene`

## Create Workflow

Check state before any `git worktree add`:

```bash
git status --short
git branch --show-current
git worktree list
```

If the current worktree is dirty, leave those changes intact. Use `--allow-dirty` when the user has authorized creating an isolated worktree while preserving them; otherwise ask before proceeding. Do not stash silently.

Use the helper when available:

```bash
scripts/setup-worktree.sh <branch> [--base <ref>] [--setup] [--test]
```

The helper creates `<project>.worktrees/<branch-slug>` from the main worktree root, handles existing local/remote branches, refuses path conflicts, and refuses dirty state unless `--allow-dirty` is passed after user approval.

`--setup` selects the declared package manager and lockfile, uses frozen installs,
and uses uv for Python. Conflicting lockfiles or manager declarations stop setup.
`--test` runs the detected baseline command. A skipped setup or test is not a pass.
Existing branch divergence is reported from local refs without fetching or merging.

Manual fallback lives in [workflow.md](references/workflow.md).

## Naming

- Root: sibling `<project>.worktrees/` directory.
- Directory: branch slug only; replace `/` with `-`.
- Examples: `fix-cron`, `feature-auth`, `bugfix-issue-123`.

## Cleanup Workflow

For one named worktree after PR merge:

```bash
scripts/cleanup-worktree.sh [branch]
```

The helper refuses unless `gh` confirms the PR is `MERGED`. Pass `--force` only after the user confirms the merge without `gh` or confirms the branch should be abandoned.

For bulk cleanup, stale worktrees, gone upstreams, or merged local branches, use `cleanup-git`.

Do not run `git pull` as part of cleanup. Pull the integration branch only after confirming the main worktree is checked out and clean.

## Failure Handling

- Worktree path exists: pick a different branch/slug; never overwrite.
- Branch already exists remotely: check it out without `-b` or use the helper.
- Dirty current worktree: preserve changes; existing authorization to isolate work permits `--allow-dirty`. Ask if the intended treatment is unclear.
- `git worktree remove` fails because the worktree is dirty: confirm before `--force`.
- `git branch -d` fails after squash/rebase PR merge: confirm the PR is `MERGED`, then use `-D`.
- Invoked from inside the worktree being removed: change to the main worktree before removing it.

## Output

```text
WORKTREE READY
==============
Action: CREATE | CLEANUP
Branch: <branch>
Path: <project>.worktrees/<slug>
Status: DONE | BLOCKED

Next:
- cd <path> and open the editor there, or
- pull the integration branch yourself after confirmed cleanup
```

For cleanup, report `DONE` only when the PR is confirmed `MERGED` or `--force` was used deliberately. Otherwise report `BLOCKED` with the script's reason.

## References

- [workflow.md](references/workflow.md) — manual fallback and edge cases
- [scripts/](scripts/) — `setup-worktree.sh` and `cleanup-worktree.sh`