using-git-worktrees

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,267 words, so you can see where the weight sits before reading.

1. 11. Detect existing isolation138 words
2. 22. Decide whether to isolate95 words
3. 33. Create the worktree481 words
4. 44. Set up the project73 words
5. 55. Check the baseline66 words
6. 66. Report61 words
7. 7What this skill does not do by itself54 words
8. 8Parallel agents37 words
9. 9Common mistakes138 words

What it holds the line on

Rules in the text

From the section “What this skill does not do by itself”.

• ✕It does not remove a worktree, delete a branch, run git worktree prune, or use --force. Those belong to the end of the task and wait for the user.
• ✕It does not reset, stash or clean the user's checkout to make room.
• ✕It does not commit anything on the user's behalf.

The skill itself

Read it before you install it

---
name: using-git-worktrees
description: Set up an isolated git worktree for a task - detect whether you are already in one, use the host's own worktree feature if it has one, otherwise run git worktree add into an ignored location, install dependencies and confirm a clean test baseline before any change. Use when starting a feature or plan that should not disturb the user's current checkout, when running parallel agents on separate branches, or when the user says "use a worktree", "isolate this work", "separate checkout" or "don't touch my branch". Not for finishing, merging or removing a worktree (see finishing-a-development-branch) or for a small edit that can safely stay in place.
license: MIT
---

# Using git worktrees

A worktree is a second checkout of the same repository, in its own directory, on its own branch. Work done there cannot disturb the user's current files, and several agents can each hold a different branch at once. This skill covers starting one safely. Ending one is a separate decision that belongs to the user.

The order is: detect, decide, create, set up, check the baseline, report. Do not create anything before the first two.

## 1. Detect existing isolation

Check whether you are already inside a linked worktree. A second one nested inside the first is almost never what anyone wants.

```bash
git_dir=$(cd "$(git rev-parse --git-dir)" && pwd -P)
common_dir=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
git branch --show-current
git rev-parse --show-superproject-working-tree
```

- If `git_dir` differs from `common_dir`, you are in a linked worktree. Do not create another. Skip to step 4 and say so: "Already in a worktree at `<path>` on branch `<name>`." If the branch name is empty the head is detached, and a branch will be needed before this work can be pushed.
- If the last command prints a path, you are inside a submodule, which is a separate repository and not a worktree. Treat it as an ordinary checkout.
- If the two directories match, this is a normal checkout. Continue.

## 2. Decide whether to isolate

- Follow what the user or the project's instructions already say about worktrees: whether to use one, and where.
- If the user asked for isolation, or their instructions declare it as practice, go ahead.
- Otherwise ask one short question before making a directory and a branch in their repository: "Want me to set up a separate worktree so your current branch stays untouched?" If they say no, work in place and skip to step 4.
- A small, self-contained edit usually does not need a worktree. Say so and let the user choose.

## 3. Create the worktree

### 3a. The host's own feature comes first

If the environment gives you a way to create a worktree (a tool, a command or a flag), use it. It manages placement, branch creation and cleanup, and a worktree made behind its back is state the host cannot see. When it returns, confirm three things before touching code: the path, the branch name, and the commit it started from. Some tools start from the remote's default branch instead of your current commit, which leaves unpushed local commits behind. Check the starting commit rather than assume it.

If the code you will change lives in a repository nested inside an outer one (an umbrella folder holding several independent repositories), find the root of the repository that owns that code, `git -C <code-dir> rev-parse --show-toplevel`, and create the worktree from that one. After creation, confirm the worktree belongs to it: `git -C <worktree> rev-parse --git-common-dir` must match the same command run in the target repository. If it does not, stop editing, report what you found, and leave the stray worktree alone. Do not delete it; it may hold changes.

### 3b. Plain git, when there is no host feature

Pick the location in this order:

1. A location the user or the project instructions declare.
2. A directory the repository already uses at its root: `.worktrees/`, then `worktrees/`.
3. Otherwise `.worktrees/` at the repository root, or a sibling directory beside the repository. A sibling is outside the project and needs no ignore check, but some sandboxes will not let you write there.

**A directory inside the repository must be ignored before you create anything in it.** Otherwise the new checkout shows up as untracked, and `git add -A` stages it as an embedded repository, with a warning. Check with a trailing slash:

```bash
git check-ignore -q -- ".worktrees/"
```

The slash matters. With a directory-only ignore rule such as `.worktrees/` and no such directory yet, the check without the slash reports "not ignored" even though the rule is there.

If the location is not ignored, add it to the repository's local exclude file, `$(git rev-parse --git-common-dir)/info/exclude`. That changes nothing that is tracked and nothing that has to be committed. Edit `.gitignore` instead, and tell the user you did, only if the team should share the rule. Do not commit a change for the user without their say-so.

Create the worktree from an explicit starting point, usually the commit you are on or a base the user names:

```bash
git worktree add -b <branch> <path> <start-point>
cd <path>
```

If the branch or path already exists, stop and report it. Do not reuse a directory you did not create. A branch can be checked out in only one worktree at a time. If git refuses for permission reasons, a sandbox is probably blocking it: tell the user, and work in place only if they agree.

## 4. Set up the project

Use the commands the project documents. If it documents none, infer from the files present: `package.json`, `Cargo.toml`, `pyproject.toml`, `requirements.txt`, `go.mod`. A fresh worktree holds only tracked files, so installed dependencies and ignored files such as `.env` are not there. Do not copy secrets or credentials in from the main checkout unless the user says to.

For Python, install into an active virtual environment, never the global interpreter. If none is active, ask first.

## 5. Check the baseline

Run the project's tests before changing anything. A clean baseline is what lets you tell your own breakage from the project's.

- Green: record the count and continue.
- Red: report the failing tests by name and ask whether to proceed or investigate. Keep the list, so a later failure can be compared against it.
- No tests exist: say so, which is different from passing.

## 6. Report

```
Worktree ready at <absolute path>
Branch <name>, started from <commit or branch>
Baseline: <N> tests, <M> failing (<names, if any>)
Created by me in this session: yes
```

Keep that last line accurate. The next stage, deciding what to do with the branch and whether to remove the directory, must not treat a worktree as yours unless you made it.

## What this skill does not do by itself

- It does not remove a worktree, delete a branch, run `git worktree prune`, or use `--force`. Those belong to the end of the task and wait for the user.
- It does not reset, stash or clean the user's checkout to make room.
- It does not commit anything on the user's behalf.

## Parallel agents

Give each agent its own worktree and its own branch, and name the branch for the task. Each one needs its own dependencies. They share one repository, so branches and commits show up in all of them.

## Common mistakes

| Mistake | Why it hurts |
|---|---|
| Making a worktree without checking whether you are in one | Nested checkouts, and confusion about which branch is which. |
| Skipping the ignore check | The worktree is staged into the user's repository as an embedded repository. |
| Checking the ignore rule without the trailing slash | A correct rule looks missing before the directory exists, and you edit files you did not need to. |
| Using `git worktree add` when the host has its own feature | The host cannot see or clean up what it did not create. |
| Trusting the new worktree's starting commit | It may not be the commit you meant. |
| Starting work on a red baseline without saying so | Every later failure becomes ambiguous. |

The second audit

What we found in the sources

It keeps the order of work of the version the others copy (obra/superpowers: detect existing isolation, prefer the host's own tool, fall back to git, check the ignore rule, set up, check a clean baseline, report) and changes the steps that edited or committed to the user's repository without asking. The git behaviours it states were checked in a scratch repository on git 2.50.1 (Apple Git-155); the skill itself has not been run against real tasks. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• obra/superpowers ↗ · Primary basis · MIT

  The order of work (detect existing isolation, then the host's native tool, then the git fallback), the git-dir versus git-common-dir comparison with a submodule check and the branch versus detached-head report, the ignore check before creating a project-local directory, per-ecosystem setup, the clean-baseline test run, the report format and the sandbox-blocked case. The rationalizations table became a short mistakes table. Most other English sources in this family read as copies, ports or condensed rewrites of it; litepowers, tapway and jamesrochabrun are independent.

• lsy041015/orchestra ↗ · Added ideas · MIT

  A small safe edit does not need a worktree; probing the ignore rule with a trailing slash so a directory-only pattern matches before the directory exists; resolving the location from the repository root; stopping when the branch or path already exists instead of reusing it; not creating a safety-only commit; installing Python requirements only into an active virtual environment; and the warning that a host tool may start from the remote's default branch, kept as 'check the starting commit' because it is one source's claim about one host.

• cheng6563/litepowers ↗ · Added ideas · MIT

  For a repository nested inside an outer one: find the root of the repository that owns the code first, compare the new worktree's git-common-dir with that repository's afterwards, and never delete a worktree made in the wrong repository before its changes are known. Also the use of the repository's local exclude file instead of editing tracked files. The body is in Chinese and was read as such.

• jamesrochabrun/skills ↗ · Added ideas · MIT

  One worktree and one branch per parallel agent, and a sibling directory as an alternative location.

• tapway/tapway-superpowers ↗ · Added ideas · MIT

  The gotchas: each worktree needs its own dependencies and env files, a branch can be checked out in only one worktree, and a worktree directory beside the repository avoids the ignore question.

What changed

• The description now says what the skill does, lists the phrases that should trigger it ("use a worktree", "isolate this work", "don't touch my branch") and has a not-for clause. The upstream description is only "Use when starting feature work that needs isolation from current workspace or before executing implementation plans" plus a short note on the mechanism.
• Rewritten as one self-contained file with no named host tools, no companion files, no plugin namespace and no persona. The one pointer to another skill is finishing-a-development-branch, written in the same refactor.
• When the chosen directory is not ignored, upstream says to add it to .gitignore and commit. Here the default is the repository's local exclude file, which changes nothing tracked; .gitignore or a commit happen only with the user's say-so.
• Consent: upstream asks before creating a worktree unless a preference is declared; one source (orchestra) says an already-authorized task needs no routine consent round. The skill asks once, only when neither the user nor the project's instructions say anything, and says a small edit may stay in place.
• Sandbox-blocked creation: upstream continues in the current directory after telling the user. Here the agent tells the user and continues in place only if they agree.
• The ignore probe uses a trailing slash (from orchestra). Without it, a directory-only rule such as .worktrees/ reported 'not ignored' while the directory did not exist yet, in a scratch repository on git 2.50.1 (Apple Git-155).
• The report gains a 'created by me in this session' line, so a later cleanup step can tell which worktrees it may touch. Upstream and its copies infer ownership from the directory name.
• Added 'no tests exist' as a separate baseline outcome, a rule not to copy .env files or credentials into the new worktree without being asked, and an explicit list of what the skill does not do by itself (remove, prune, force, reset, commit). These are the author's additions, not taken from a source.
• Removed 'Announce at start' and 'your human partner'.

Problems found in the sources

• !obra/superpowers: If the directory is not ignored it says to add it to .gitignore and commit, which changes the user's repository without asking. The ignore check `git check-ignore -q .worktrees` has no trailing slash: with a directory-only rule and no such directory yet it reported 'not ignored' in a scratch repository on git 2.50.1 (Apple Git-155), so the default path would trigger an unneeded edit and commit. It says GIT_DIR differs from GIT_COMMON inside a submodule; in a plain one-submodule test on the same git version they were equal, so the stated reason for the superproject check did not reproduce (the check itself is harmless). It runs `pip install -r requirements.txt` with no check of which interpreter is active, names host tools (EnterWorktree, WorktreeCreate), and uses 'your human partner'. Its sandbox fallback works in the user's current checkout without asking.
• !lsy041015/orchestra: The closest to a safe version of upstream: it probes the ignore rule correctly, refuses to reuse an existing branch or path, and avoids a safety-only commit. It still ties ownership to an orchestra-owned-worktree marker file and names a Claude Code tool and its worktree.baseRef setting; the claim that the tool branches from origin's default branch was not verified here. The path-resolution shell function is long for the job.
• !cheng6563/litepowers: A distinct skill for repositories nested inside an outer one, not a copy of upstream. It uses `realpath -m`, which the realpath on macOS rejects ('illegal option -- m' on the machine used for this audit). Its examples contain the author's own local Windows paths and project names. The body is Chinese with an English sentence appended to the description.
• !jamesrochabrun/skills: The downloaded SKILL.md refers to scripts/create_worktree.sh, list_worktrees.sh, cleanup_worktrees.sh and sync_worktree.sh and to three files under references/, none of which is in the file. Its troubleshooting suggests `git reset --hard origin/main` to throw away a worktree's changes, and its patterns run `git checkout main`, `git merge` and `git push origin main` with no confirmation. It gives '3-5 worktrees max for best performance' and fixed cleanup and sync cadences with no basis. It says a branch name such as feature/my_feature causes 'fatal: invalid reference'; `git worktree add -b feature/my_feature` succeeded in a scratch repository on git 2.50.1 (Apple Git-155). It uses emoji and box-drawing output and the Claude Code /init command.
• !xenitV1/claude-code-maestro: Offers `git worktree remove --force` for uncommitted changes in its cleanup section with no confirmation step. Wraps the text in custom XML-like section tags, uses emoji, refers to @-skills that are not in the file, and has a Ralph Wiggum section that depends on another tool.
• !gylove1994/superpowers-deepseek-v4: Adds an Integration paragraph that depends on a skill and a session record (confirming-worktree-before-edit, 'worktree consent') that are not part of this file. The step headings go Step 0, Step 1, Step 3, Step 4: there is no Step 2, though the text says 'Skip to Step 3'.
• !mzored/superpowers-cc-to-codex: A header comment says it ships under the superpowers: namespace and that the upstream skill should be disabled when this one is active. It tells the agent to add the directory to .gitignore and commit ('Fix broken things immediately'), and its Integration section names skills that are not in the file.
• !thepragmaticbear/bearpaws: A condensed rewrite wrapped in custom XML-like tags, with bp: namespaced skill references and a bearpaws-specific global directory. It adds to .gitignore and commits 'immediately'.
• !tapway/tapway-superpowers: Short and accurate as far as it goes, but its workflow ends in the template author's own slash commands and tells the agent never to push manually, a policy of that template. It has no baseline-test step and no check for an existing worktree.

What was dropped

• The four wrapper scripts and three reference files that jamesrochabrun/skills points at, its /init advice and its Claude Code session instructions.
• jamesrochabrun's merge-to-main-and-push patterns, its git reset --hard troubleshooting entry, and its numbers (3-5 worktrees 'for best performance', weekly cleanup, daily sync), none of which comes with a basis.
• The Windows PowerShell blocks and the Ralph Wiggum integration from xenitV1/claude-code-maestro.
• The global ~/.config/<vendor>/worktrees location found in several copies, which is tied to one vendor's directory name. A sibling directory covers the same need.
• orchestra's ownership marker file and its long path-resolution shell function; litepowers' realpath and cygpath code and its examples drawn from the author's own Windows paths.
• tapway's references to its own slash commands (/simplify, /review, /pr, /cleanup) and a tdd skill.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/using-git-worktrees ~/.claude/skills/

Pairs with