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.

Language note: This skill is language-agnostic. Use whichever language the user prefers. The operational instructions below are platform-independent.

When to Use

Use when:

• Starting feature work that needs isolation
• Before executing implementation plans
• Need to protect current branch from changes

Don't use when:

• Simple bug fix on current branch
• No isolation needed
• Working on main/master intentionally

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 you are not in a submodule:

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

If GIT_DIR != GIT_COMMON (and not a submodule): You are already in a linked worktree. Skip to Step 2. Do NOT create another worktree.

Report with branch state:

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

If GIT_DIR == GIT_COMMON (or in a submodule): You are in a normal repo checkout.

Always ask for explicit user consent before creating a worktree:

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

If the user declines consent, work in place and skip further steps.

Step 1: Create Isolated Workspace

1a. Native Worktree Tools (preferred)

Check if you already have a way to create a worktree (e.g., EnterWorktree, WorktreeCreate, a /worktree command, or a --worktree flag). If you do, use it and skip to Step 2.

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

Only proceed to Step 1b if you have no native worktree tool available.

1b. Git Worktree Fallback

Only use this if Step 1a does not apply.

Directory Selection

1. Check for explicit user preference for worktree directory.
2. Check for an existing project-local worktree directory:

   ls -d .worktrees 2>/dev/null     # Preferred (hidden)
   ls -d worktrees 2>/dev/null      # Alternative
   

   If found, use it. If both exist, .worktrees wins.
3. Default to .worktrees/ at the project root if no other guidance.

Safety Verification

Check if the directory is gitignored before creating a worktree:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored: Report to the user that the directory is not in .gitignore. Ask the user whether to add it. If the user approves, edit .gitignore and leave the change uncommitted — do not commit automatically. Inform the user they should review and commit the change themselves.

Create the Worktree

path="$LOCATION/$BRANCH_NAME"

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

Sandbox fallback: If git worktree add fails with a permission error, tell the user the sandbox blocked worktree creation and work in the current directory instead.

Step 2: Report Ready

After worktree creation (or detection of existing isolation), report status:

Worktree ready at <full-path>
Branch: <name>

Do NOT automatically install dependencies, build, or run tests. This skill's scope is limited to workspace isolation only.

If dependency installation or test execution is needed, ask the user explicitly:

"Would you like me to install dependencies or run baseline tests in this worktree?"

Only proceed with setup/test commands after explicit user approval.

Step 3: Cleanup

When the user is done with the worktree:

# Ask user before removing
git worktree remove "$path"
git worktree prune

Always ask for explicit confirmation before removing a worktree. Warn the user if there are uncommitted changes:

git -C "$path" status --porcelain

If there are uncommitted changes, warn the user and ask whether to force-remove or keep the worktree.

Common Rationalizations

Quick Reference

Remember

• Detect existing isolation first
• Use native tools when available
• Fall back to git worktrees only when needed
• Verify directory is ignored (ask before editing .gitignore, never auto-commit)
• Never auto-install dependencies or run tests without explicit user consent
• Always ask before removing a worktree
• Never fight the harness