Deploy and launch · How to use a skill

set-up-git-worktrees-and-finish-branch

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.

Version 1.0 · Updated 2026-10-31

View raw SKILL.md

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/raw' -o ~/'.claude/skills/set-up-git-worktrees-and-finish-branch/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/files/LICENSE.txt' -o ~/'.claude/skills/set-up-git-worktrees-and-finish-branch/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/raw' -o '.cursor/skills/set-up-git-worktrees-and-finish-branch/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/files/LICENSE.txt' -o '.cursor/skills/set-up-git-worktrees-and-finish-branch/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/raw' -o '.agents/skills/set-up-git-worktrees-and-finish-branch/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/set-up-git-worktrees-and-finish-branch/files/LICENSE.txt' -o '.agents/skills/set-up-git-worktrees-and-finish-branch/LICENSE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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.

   git worktree add .worktrees/my-feature -b feature/my-feature
   cd .worktrees/my-feature

1. Set up the project. Run the install command for the stack (npm install, pip install -r requirements.txt, cargo build or go mod download).
2. 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

1. Verify. Run the full test suite and checks. If anything fails, stop and fix it. Do not offer to merge failing work.
2. Confirm the base branch. Usually main. Check with git merge-base HEAD main, or ask.
3. Offer clear options. Ask the user to choose:
4. Merge into the base branch locally.
5. Push the branch and open a pull request.
6. Keep the branch as it is for later.
7. Discard the work.
8. 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.

1. 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

Adapted from Jesse Vincent (obra/superpowers, 'using-git-worktrees' and 'finishing-a-development-branch') (Copyright (c) 2025 Jesse Vincent), MIT License. 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.

Licence: MIT License. Attribution when you reuse it: Based on work by Jesse Vincent (obra/superpowers, 'using-git-worktrees' and 'finishing-a-development-branch') (Copyright (c) 2025 Jesse Vincent, MIT License), https://github.com/obra/superpowers/tree/2ce8aa15d05bd57213e6f746f953aafb7ded7a8b/skills/using-git-worktrees; adapted by TheSkillVault, https://theskillvault.ai