worktree-management

Forge: Worktree Management

Overview

This skill provides reference knowledge for git worktree operations used by the forge executing skill. It is loaded at session start via the SessionStart hook.

Conventions

• Worktree base path: $SESSION_DIR/worktrees/ (where SESSION_DIR = .forge/sessions/<id>/)
• Branch naming: forge/s<id>/batch-<N>-<timestamp> (e.g., forge/s1/batch-1-1708300000)
• Tag naming: forge/checkpoint/s<id>/batch-<N>-pre-merge
• Worktrees are ephemeral — created per parallel batch, destroyed after merge
• Each session has its own isolated worktree directory — no cross-session conflicts

Operations

Create a Worktree for a Batch

# Get timestamp for unique branch name
TIMESTAMP=$(date +%s)
SESSION_ID=<id>
BRANCH="forge/s${SESSION_ID}/batch-${BATCH_NUM}-${TIMESTAMP}"
WORKTREE_PATH=".forge/sessions/${SESSION_ID}/worktrees/batch-${BATCH_NUM}"

# Ensure worktree base directory exists
mkdir -p ".forge/sessions/${SESSION_ID}/worktrees"

# Create worktree with new branch from current HEAD
git worktree add "$WORKTREE_PATH" -b "$BRANCH"

Work in a Worktree

Implementer agents receive the worktree path as their working directory. All file operations happen within the worktree. The main branch remains untouched during parallel execution.

Merge Worktree Back

# From the main working directory (not the worktree)
BRANCH="forge/s${SESSION_ID}/batch-${BATCH_NUM}-${TIMESTAMP}"
WORKTREE_PATH=".forge/sessions/${SESSION_ID}/worktrees/batch-${BATCH_NUM}"

# Merge the batch branch
git merge "$BRANCH" --no-edit

# If merge conflict: STOP and ask the user
# Do NOT auto-resolve conflicts

Clean Up

# Remove worktree
git worktree remove "$WORKTREE_PATH" --force

# Delete the branch
git branch -d "$BRANCH"

Clean Up All Worktrees for a Session (Emergency)

SESSION_ID=<id>
SESSION_DIR=".forge/sessions/${SESSION_ID}"

# List all forge worktrees for this session
git worktree list | grep "${SESSION_DIR}/worktrees"

# Remove them all
for wt in "${SESSION_DIR}/worktrees/batch-"*; do
  git worktree remove "$wt" --force 2>/dev/null
done

# Clean up any leftover branches for this session
git branch | grep "forge/s${SESSION_ID}/" | xargs -r git branch -D

List All Sessions with Active Worktrees

# See all active forge worktrees across all sessions
git worktree list | grep ".forge/sessions/"

Rules

1. Never auto-resolve merge conflicts — always ask the user
2. Clean up immediately after a batch completes (success or failure)
3. One worktree per parallel batch — not per task
4. Sequential batches don't need worktrees — they work on main directly
5. If worktree creation fails — fall back to sequential execution for that batch
6. .forge/sessions/*/worktrees/ should be in .gitignore
7. Session isolation — never touch worktrees or branches that belong to a different session ID