---
name: set-up-git-worktrees-and-finish-branch
description: Runs a feature from start to finish in its own git worktree - check for existing isolation, create an ignored worktree, install and run baseline tests - then finishes the branch by verifying tests and offering merge, pull request or keep. Use when starting isolated feature work, running parallel agents on one repo, setting up a git worktree, or finishing and cleaning up a development branch.
license: MIT
metadata:
  category: deployment
  tags: "workflow,agents,productivity,verification"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-31"
  status: published
  aliases: "using-git-worktrees,finishing-a-development-branch,git-worktree,finish-branch"
  source_url: "https://github.com/obra/superpowers/tree/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/using-git-worktrees"
  source_license: MIT
  copyright: "Copyright (c) 2025 Jesse Vincent"
  original_author: "Jesse Vincent (obra/superpowers, 'using-git-worktrees' and 'finishing-a-development-branch')"
  modified: "Adapted by TheSkillVault: merged two skills (using-git-worktrees and finishing-a-development-branch, same commit) into one start-to-finish flow; renamed to the verb-first house style; plain-language steps; removed 'announce at start' lines and links to other superpowers skills; added when-to-use, gotchas, portability and done-when sections."
  imported_on: "2026-10-31"
---

# Set up git worktrees and finish the branch

A git worktree is a second working folder for the same repository, on its own branch. Work there cannot clash with your main checkout, and several agents can work in parallel. This skill sets one up safely, then finishes the branch cleanly when the work is done.

## When to use
- Starting a feature that should not touch your current checkout.
- Running two or more AI agents on the same repo at the same time.
- The work is done and tests pass, and you need to merge, open a pull request or tidy up.

## Steps

### Part 1: Start in a worktree
1. **Check if you are already isolated.** Compare `git rev-parse --git-dir` with `git rev-parse --git-common-dir`. If they differ, you are already in a worktree: skip to step 5. If `git rev-parse --show-superproject-working-tree` prints a path, you are in a submodule: treat it as a normal checkout.
2. **Prefer the tool's own worktree feature.** If your agent or editor has a built-in worktree or sandbox option, use it instead of raw git.
3. **Pick an ignored folder.** Use an existing `.worktrees/` folder if there is one, or the folder named in `AGENTS.md` or `CLAUDE.md`. Otherwise use `.worktrees/`. Confirm git ignores it with `git check-ignore -q .worktrees`. If not, add it to `.gitignore` and commit that first.
4. **Create the worktree.**
   ```bash
   git worktree add .worktrees/my-feature -b feature/my-feature
   cd .worktrees/my-feature
   ```
5. **Set up the project.** Run the install command for the stack (`npm install`, `pip install -r requirements.txt`, `cargo build` or `go mod download`).
6. **Run the tests once before changing anything.** If they already fail, report it and ask before continuing, so new failures are not blamed on your work.

### Part 2: Finish the branch
7. **Verify.** Run the full test suite and checks. If anything fails, stop and fix it. Do not offer to merge failing work.
8. **Confirm the base branch.** Usually `main`. Check with `git merge-base HEAD main`, or ask.
9. **Offer clear options.** Ask the user to choose:
   1. Merge into the base branch locally.
   2. Push the branch and open a pull request.
   3. Keep the branch as it is for later.
   4. Discard the work.
10. **Do the chosen option.**
    - *Merge:* switch to the base branch in the main checkout, pull, `git merge feature/my-feature`, run the tests again, then delete the branch with `git branch -d`.
    - *Pull request:* `git push -u origin feature/my-feature`, then open the PR (for example `gh pr create`). Keep the worktree until it merges.
    - *Keep:* report the branch name and worktree path. Change nothing.
    - *Discard:* list the branch, its commits and the worktree path, and ask the user to type `discard` to confirm. Only then run `git branch -D`.
11. **Clean up the worktree** (merge or discard only). From the main checkout, run `git worktree remove .worktrees/my-feature`, then `git worktree prune`.

## Gotchas
- A worktree folder that git does not ignore gets its files committed by accident. Step 3 prevents this.
- One branch can be checked out in only one worktree at a time.
- Each worktree needs its own install step. `node_modules` and build output are not shared.
- If `git worktree remove` refuses, the folder has uncommitted changes. Look at them before doing anything else.

## Safety
- Never force-push and never use `git worktree remove --force` without the user's clear yes.
- Never discard work without the typed `discard` confirmation.
- Copying `.env` files into a new worktree copies secrets. Copy only what the tests need, and keep `.env` in `.gitignore`.

## Works with other tools
Plain git works in any terminal and any AI tool. Claude Code, Cursor, Codex and other agents also have their own worktree or sandbox modes; if you use one, skip steps 3 and 4 and follow the rest. Jujutsu's `jj workspace` is the equivalent in jj.

## Done when
- The work happened in its own worktree, and the baseline tests were run before any change.
- The final tests pass, and the user picked merge, pull request, keep or discard.
- Merged or discarded worktrees are removed, and nothing was force-pushed or deleted without a clear yes.

## Example prompt
"Set up a separate worktree for the new billing feature, run the tests first, and when we are done help me merge it or open a PR."

---
Adapted from "using-git-worktrees" and "finishing-a-development-branch" in obra/superpowers by Jesse Vincent (MIT). See LICENSE.txt. Second source: https://github.com/obra/superpowers/tree/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/finishing-a-development-branch