using-git-worktrees

Using Git Worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

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

[!NOTE] 📋 Harness-managed worktrees land in the pinned location automatically. orc ships WorktreeCreate/WorktreeRemove hooks (hooks/scripts/worktree-*.sh): any worktree Claude Code itself creates (--worktree, or an agent with isolation: worktree) is placed under <repo>/.orc/.worktrees/<sanitized-branch> and cleaned up only when the tree is clean. This skill's manual process below applies when YOU create the worktree.

Directory Selection Process

Iron rule: orc worktrees always live under .orc/.worktrees/ — at the repo root or, in workspace mode, the workspace root. Never under $HOME, never elsewhere. .orc/ is always git-ignored in an orc project, so worktree contents can never pollute the tree. There is no "ask the user where", no global location, and no CLAUDE.md location override — the location is fixed by design.

Exactly two cases:

Workspace mode

If the caller sourced lib/workspace-detect.sh and ORC_CONTEXT=workspace, use the workspace-shared trees root, keyed per repo:

path="$ORC_WORKSPACE_ROOT/.orc/.worktrees/<repo>/<branch>"

Use this when the caller provides a repo + branch pair (e.g. from /orc:start or /orc:flow Phase 4 in workspace mode). Workspace-mode worktrees are always per-repo and always require a target repo — if the caller hasn't passed repo, treat it as repo mode for the current repo instead.

Repo mode (default)

Otherwise use the current repo's own .orc/.worktrees/:

path="$(git rev-parse --show-toplevel)/.orc/.worktrees/<branch>"

Safety Verification

MUST confirm .orc/ is ignored before creating the worktree. It almost always is (orc scaffolds it into .gitignore), but verify — a worktree inside a tracked .orc/ would get its entire checkout staged.

# Workspace mode: check the workspace root; repo mode: check the repo root.
root="${ORC_WORKSPACE_ROOT:-$(git rev-parse --show-toplevel)}"
git -C "$root" check-ignore -q .orc

If NOT ignored (non-zero exit), fix it immediately before proceeding:

1. Append .orc/ to the root .gitignore
2. Commit that change
3. Then create the worktree

Why critical: Prevents accidentally committing worktree contents to the repository.

Creation Steps

1. Resolve Roots and Branch

# Repo mode
repo_root="$(git rev-parse --show-toplevel)"

# Workspace mode: the caller supplies $ORC_WORKSPACE_ROOT, $REPO, $BRANCH_NAME.
# Project name is the explicit `repo` argument (e.g. `api`), NOT derived from
# git rev-parse (which would lose the workspace context).

2. Create Worktree

# Determine full path — always under .orc/.worktrees/, never under $HOME
if [ "$ORC_CONTEXT" = "workspace" ] && [ -n "$REPO" ]; then
  # Workspace mode: caller supplied $ORC_WORKSPACE_ROOT, $REPO, $BRANCH_NAME
  path="$ORC_WORKSPACE_ROOT/.orc/.worktrees/$REPO/$BRANCH_NAME"
  cd "$ORC_WORKSPACE_ROOT/$REPO"
else
  # Repo mode: the current repo's own .orc/.worktrees/
  path="$(git rev-parse --show-toplevel)/.orc/.worktrees/$BRANCH_NAME"
fi

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. Run Project Setup

Auto-detect and run appropriate setup:

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. Verify Clean Baseline

Run tests to verify the worktree starts clean:

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

If tests fail: surface a ⚠️ Caution callout (baseline tests already failing in the fresh worktree — findings won't be attributable to your change), then ask whether to proceed or investigate.

If tests pass: Report ready.

5. Report Location

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Situation → action table, a worked transcript, and the calling skills: EXAMPLES.md. Read it on a first run or when a caller passes an unusual repo/branch pair.

Common Mistakes

Problem/fix pairs: COMMON-MISTAKES.md. Read it when a step fails.

Red Flags

Red Flags

Never:

• Create a worktree anywhere but .orc/.worktrees/ (repo root or workspace root)
• Create a worktree under $HOME, .worktrees/, or a sibling directory
• Create the worktree without confirming .orc/ is ignored
• Skip baseline test verification
• Proceed with failing tests without asking

Always:

• Place worktrees under .orc/.worktrees/ — repo root in repo mode, workspace root in workspace mode
• Confirm .orc/ is ignored before creating the worktree
• Auto-detect and run project setup
• Verify clean test baseline