using-git-worktrees

intent

use git worktrees to spin up isolated workspaces that share your repository but let you work on multiple branches simultaneously without constant switching. when you need to context-switch between features, bugs, or experiments without losing your current work state, worktrees eliminate the friction of stashing, switching, and unstashing. worktrees are your go-to when you're juggling parallel work streams in the same project.

inputs

required

• active git repository (verified via git rev-parse --show-toplevel)
• branch name to create the worktree on (e.g. feature/auth, bugfix/login)
• access to project root directory with read-write permissions

external connections

• git installation (local, no auth needed)
• project dependency managers (npm, cargo, pip, poetry, go, etc.) installed and functional on your system
• CLAUDE.md file (optional, in project root) for worktree directory preferences

environment context

• current working directory must be inside an initialized git repository
• network access not required (purely local operation)

procedure

1. announce the skill log to user: "i'm using the using-git-worktrees skill to set up an isolated workspace."

inputs: user request, project context outputs: user acknowledgment logged

2. detect project name run: project=$(basename "$(git rev-parse --show-toplevel)")

inputs: git repository state outputs: $project variable set (e.g. "myproject")

3. select worktree directory follow this priority order:

a) check for existing .worktrees directory: ls -d .worktrees 2>/dev/null b) check for existing worktrees directory: ls -d worktrees 2>/dev/null c) check CLAUDE.md for preference: grep -i "worktree.*director" CLAUDE.md 2>/dev/null d) if none found, ask user to choose between .worktrees/ (hidden, project-local) or ~/.config/superpowers/worktrees/<project-name>/ (global)

inputs: filesystem state, CLAUDE.md (optional), user input (conditional) outputs: $LOCATION variable set to selected directory

4. verify directory safety (project-local only) if location is .worktrees or worktrees:

• run: git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
• if directory is NOT ignored, add it to .gitignore immediately, commit the change, then proceed
• rationale: prevents accidental commits of worktree content

if location is global (~/.config/superpowers/worktrees/):

• skip ignore check (outside project repo)

inputs: filesystem state, .gitignore content outputs: .gitignore updated if needed, directory confirmed safe

5. construct full worktree path if location is .worktrees or worktrees: path="$LOCATION/$BRANCH_NAME" if location is global: path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"

inputs: $LOCATION, $BRANCH_NAME, $project outputs: $path variable set to full worktree directory path

6. create the worktree run: git worktree add "$path" -b "$BRANCH_NAME" run: cd "$path"

inputs: $path, $BRANCH_NAME outputs: new git worktree directory created, current directory changed to worktree root

7. auto-detect and install dependencies check for project manifest files in order and run appropriate install:

• if package.json exists: npm install
• if Cargo.toml exists: cargo build
• if requirements.txt exists: pip install -r requirements.txt
• if pyproject.toml exists: poetry install
• if go.mod exists: go mod download

skip if no manifest found (bare project).

inputs: project root files outputs: dependencies installed in worktree

8. run baseline test suite detect and execute project tests:

• node: npm test
• rust: cargo test
• python: pytest
• go: go test ./...

skip if no test runner detected.

inputs: project test configuration outputs: test results (pass/fail counts, output log)

9. report worktree ready or failure if tests pass: report Worktree ready at <full-path> / Tests passing (<N> tests, 0 failures) / Ready to implement <feature-name>

if tests fail: report failure details, ask user whether to proceed or investigate before continuing.

inputs: test results, $path, feature name outputs: status message to user, proceed/abort decision

decision points

directory location selection

• if .worktrees exists: use it (skip .worktrees/ check, verify ignored)
• else if worktrees exists: use it (verify ignored)
• else if CLAUDE.md contains worktree directory preference: use stated preference without prompting
• else: ask user to choose between project-local (.worktrees/) or global (~/.config/superpowers/worktrees/<project-name>/)

ignore verification (project-local only)

• if directory is ignored per git check-ignore: proceed to worktree creation
• if directory is NOT ignored: add to .gitignore, commit immediately, then proceed
• if location is global: skip ignore check entirely

dependency installation

• if project manifest (package.json, Cargo.toml, requirements.txt, pyproject.toml, go.mod) exists: run detected installer
• if no manifest found: skip installation, report "no dependencies detected"

test baseline verification

• if test suite detected and all tests pass: proceed (report pass count)
• if test suite detected and tests fail: report failures, ask user explicitly whether to proceed or investigate
• if no test suite found: report "no test suite detected", proceed with user acknowledgment

error handling on worktree creation

• if branch already has a worktree: report error, ask whether to attach to existing worktree or delete and recreate
• if path already exists (not a git worktree): report error, ask user whether to use different branch name or location
• if git command fails (permission, network timeout): report error and stop

network or timeout issues

• if dependency install times out (e.g. npm registry slow): report timeout, offer retry or skip
• if git operations timeout: stop and report, ask user to verify git connectivity

output contract

on success

• worktree directory created at <full-path> (e.g. /Users/jesse/myproject/.worktrees/feature/auth or ~/.config/superpowers/worktrees/myproject/feature/auth)
• all dependencies installed (if applicable) and verified via npm install, cargo build, etc.
• baseline test suite run and all tests passing (if applicable)
• current shell working directory is inside the new worktree
• output report includes: worktree location, test count/status, feature name, ready message

on failure

• if directory already occupied: error message + exit without creating worktree
• if ignore verification fails: .gitignore updated with directory entry + commit created, then creation proceeds
• if tests fail: failure report logged, user asked for permission to continue, creation paused pending decision
• if dependency install fails: error message + ask retry or skip

file locations

• worktree metadata stored in .git/worktrees/ (git-managed, auto-created)
• worktree content stored in $path (user-specified directory)
• .gitignore updated in project root if needed

outcome signal

user knows it worked when

• shell prompt changes to reflect new worktree directory (e.g. ~/.../myproject/.worktrees/feature/auth $)
• pwd confirms location is the new worktree path
• git status shows clean working tree (or expected branch state)
• test output shows all tests passing (if run)
• user can immediately start coding without setup friction

red flags (did not work)

• shell still in original project directory
• worktree command returned error (branch exists, path collision, permission denied)
• tests fail without user permission to proceed
• dependencies not installed (manifest detected but install skipped or errored)
• directory not added to .gitignore when it should be