Using git worktrees

Skill tspry/superpowers-devops/skills/using-git-worktrees

Use before starting infrastructure or feature work that needs isolation from the current workspace — ensures an isolated workspace exists via native tools or git worktree fallbackFrom its SKILL.md

Install

npx -y skills add tspry/superpowers-devops --skill using-git-worktrees

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.4 KB, as published. Nobody here has run it

Using Git Worktrees

Overview

Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.

Core principle: Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Step 0: Detect Existing Isolation

Before creating anything, check if you are already in an isolated workspace.

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)
BRANCH=$(git branch --show-current)

Submodule guard: GIT_DIR != GIT_COMMON is also true inside git submodules. Before concluding "already in a worktree," verify:

# If this returns a path, you're in a submodule — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

If GIT_DIR != GIT_COMMON (and not a submodule): Already in a linked worktree. Skip to Step 3.

Report:

On a branch: "Already in isolated workspace at <path> on branch <name>."
Detached HEAD: "Already in isolated workspace at <path> (detached HEAD, externally managed)."

If GIT_DIR == GIT_COMMON (or in a submodule): Normal repo checkout. Ask for consent:

"Would you like me to set up an isolated worktree? It protects your current branch from changes."

If user declines, work in place and skip to Step 3.

Step 1: Create Isolated Workspace

Try in this order:

1a. Native Worktree Tools (preferred)

Do you have a tool like EnterWorktree, WorktreeCreate, /worktree, or --worktree? If so, use it and skip to Step 3.

Native tools handle directory placement, branch creation, and cleanup automatically.

1b. Git Worktree Fallback

Only when no native tool is available:

# Create worktree with a new branch
git worktree add -b feature/<branch-name> .worktrees/<branch-name> main

# Or for a specific base branch
git worktree add -b infra/<change-name> .worktrees/<change-name> origin/main

# List worktrees
git worktree list

Step 2: Enter the Worktree

cd .worktrees/<branch-name>
# All changes here are isolated from the main working directory

Step 3: Project Setup

Once in the isolated workspace, confirm you're on the expected branch and proceed with the planned work.

Cleanup

Cleanup is handled by superpowers-devops:finishing-a-development-branch at the end of the work. Only clean up worktrees you created:

# From main repo root (NOT from inside the worktree)
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove .worktrees/<branch-name>
git worktree prune  # clean up stale registrations

Safety Rules

Never run destructive infra commands (terraform destroy, kubectl delete) without confirming the target environment
Always confirm which branch/worktree you're in before applying changes
Do NOT run git worktree remove from inside the worktree being removed
Only clean up worktrees under .worktrees/ or worktrees/
Run git worktree prune after removal as self-healing