git-worktrees

name	git-worktrees
description	Create, list, and remove isolated git worktrees for monorepo - enables parallel feature work without branch switching

Git Worktrees for YourProject

Overview

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

Worktree location: ../YourProject-Worktrees (above monorepo root) Full path: $HOME/dev/YourProject-Worktrees

Announce at start: "I'm using the git-worktrees skill to [create/list/remove] a worktree."

Operations

1. List Worktrees

Show all active worktrees with rich status information.

# Get worktree list
git worktree list --porcelain

Format output as:

Worktrees:
  carlos/auth-refactor
    Path: ../YourProject-Worktrees/carlos/auth-refactor
    Status: 3 uncommitted changes
    Behind main: 2 commits

  carlos/fix-player
    Path: ../YourProject-Worktrees/carlos/fix-player
    Status: clean
    Behind main: 0 commits

To gather status for each worktree:

# For each worktree path, check uncommitted changes
git -C "$WORKTREE_PATH" status --porcelain | wc -l

# Check commits behind main
git -C "$WORKTREE_PATH" rev-list --count HEAD..origin/main

If no worktrees exist: "No active worktrees."

---

2. Create Worktree

Create an isolated workspace for a branch.

Step 1: Determine Branch and Path

# Branch naming follows carlos/ prefix convention
BRANCH="carlos/feature-name"

# Extract branch name without prefix for folder naming
BRANCH_NAME="${BRANCH#carlos/}"

# Path preserves hierarchy
# carlos/auth-refactor → YourProject-Worktrees/carlos/auth-refactor
WORKTREE_BASE="$HOME/dev/YourProject-Worktrees"
WORKTREE_PATH="$WORKTREE_BASE/$BRANCH"

Step 2: Check if Branch Exists

# Check local branches
git show-ref --verify --quiet "refs/heads/$BRANCH" && echo "local"

# Check remote branches
git show-ref --verify --quiet "refs/remotes/origin/$BRANCH" && echo "remote"

If branch exists (local or remote): Proceed silently.

If branch does NOT exist: Confirm before creating.

Branch `carlos/auth-refactor` doesn't exist. Create from `main`? (Y/n)

• If confirmed: proceed with -b flag
• If declined: abort

Step 3: Ask for Changelog Folder (if not specified)

IMPORTANT: Each worktree needs to know where its changelog files belong.

If the user did not specify a changelog folder:

Which folder should contain the changelog for this work?

Examples:
  - .claude (for cross-cutting work)
  - apps/website (for website changes)
  - apps/backend (for backend changes)
  - packages/mylib (for library changes)

Changelog folder:

Store the response as CHANGELOG_FOLDER.

Step 4: Create Parent Directory

# Ensure parent directory exists (for hierarchy)
mkdir -p "$(dirname "$WORKTREE_PATH")"

Step 5: Create Worktree

# For existing branch
git worktree add "$WORKTREE_PATH" "$BRANCH"

# For new branch (after confirmation)
git worktree add -b "$BRANCH" "$WORKTREE_PATH" main

Step 6: Push Branch to Remote

# Set upstream tracking (works for new or existing local-only branches)
git -C "$WORKTREE_PATH" push -u origin HEAD

If branch already has remote tracking: This step succeeds silently. If push fails (permissions, etc.): Report error but continue - user can push later.

Step 7: Install Dependencies

cd "$WORKTREE_PATH"
pnpm install

This step is mandatory - worktree must be immediately ready for work.

Step 8: Initialize Changelog Structure

Create the changelog folder and project reference in the worktree:

# Create changelog folder structure
CHANGELOG_PATH="$WORKTREE_PATH/$CHANGELOG_FOLDER/changelog/$BRANCH_NAME"
mkdir -p "$CHANGELOG_PATH"

# Get timestamp
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S %Z')

Create CHANGELOG.md:

# <Branch Title>

Start date: <TIMESTAMP>

<Brief description of branch purpose>

## Changes

Create PLAN.md:

# <Branch Title>

Start date: <TIMESTAMP>

## Overview

<Brief description of branch purpose>

## Plan

- [ ] Phase 1: ...
- [ ] Phase 2: ...

## Open Questions

- ...

Create project reference file:

# Write to .claude/current-project.txt in the worktree
mkdir -p "$WORKTREE_PATH/.claude"
echo "$CHANGELOG_FOLDER/changelog/$BRANCH_NAME" > "$WORKTREE_PATH/.claude/current-project.txt"

Step 9: Report Success

Worktree created:
  Branch: carlos/auth-refactor
  Path: ../YourProject-Worktrees/carlos/auth-refactor
  Changelog: apps/website/changelog/auth-refactor
  Dependencies: installed

To work in this worktree, start a new Claude session in:
  cd ../YourProject-Worktrees/carlos/auth-refactor

Do NOT change working directory. User starts a new session manually.

---

3. Remove Worktree

Clean up a worktree with full safeguards.

Step 1: Verify Worktree Exists

git worktree list | grep -q "$WORKTREE_PATH"

If not found: "Worktree not found at $WORKTREE_PATH"

Step 2: Check for Uncommitted Changes

CHANGES=$(git -C "$WORKTREE_PATH" status --porcelain | wc -l)

If changes exist (CHANGES > 0):

Cannot remove worktree - 3 uncommitted changes found:
  M apps/website/src/app/page.tsx
  A apps/website/src/components/NewFeature.tsx
  ? apps/website/src/utils/helper.ts

Commit or stash changes before removing.

STOP HERE. Do not proceed until changes are resolved.

Step 3: Get Branch Name

BRANCH=$(git -C "$WORKTREE_PATH" rev-parse --abbrev-ref HEAD)

Step 4: Remove Worktree

git worktree remove "$WORKTREE_PATH"

Step 5: Check if Branch is Merged

# Check if branch is merged into main
git branch --merged main | grep -q "$BRANCH" && echo "merged"

Step 6: Offer Branch Deletion

If branch is merged:

Branch `carlos/auth-refactor` is merged into main. Delete it? (Y/n)

If confirmed:

git branch -d "$BRANCH"
# Also delete remote if exists
git push origin --delete "$BRANCH" 2>/dev/null || true

If branch is NOT merged:

Branch `carlos/auth-refactor` is NOT merged into main.
Delete anyway? This may lose work. (y/N)

If confirmed (requires explicit "y"):

git branch -D "$BRANCH"

Step 7: Clean Empty Directories

# Remove empty parent directories
PARENT=$(dirname "$WORKTREE_PATH")
rmdir "$PARENT" 2>/dev/null || true

Step 8: Report Success

Worktree removed:
  Path: ../YourProject-Worktrees/carlos/auth-refactor
  Branch: deleted (was merged)
  Cleanup: complete

---

Quick Reference

Task	Command Pattern
List worktrees	git worktree list + status checks
Create for existing branch	git worktree add "$PATH" "$BRANCH"
Create for new branch	git worktree add -b "$BRANCH" "$PATH" main
Remove worktree	git worktree remove "$PATH"
Delete merged branch	git branch -d "$BRANCH"
Delete unmerged branch	git branch -D "$BRANCH"

Path Reference

Item	Path
Main repo	$HOME/dev/YourProject
Worktrees root	$HOME/dev/YourProject-Worktrees
Example worktree	YourProject-Worktrees/carlos/auth-refactor
Changelog location	<worktree>/<folder>/changelog/<branch-name>
Project reference	<worktree>/.claude/current-project.txt

Changelog Folder Examples

Work Type	Changelog Folder
Cross-cutting / tooling	.claude
Website changes	apps/website
Backend service	apps/backend
Shared library	packages/mylib
Infrastructure	apps/infrastructure
Mobile app	apps/mobile

Monorepo Notes

• Package manager: pnpm (not npm)
• Build system: Turborepo
• Branch prefix: carlos/ (project owner convention)
• Install command: pnpm install (installs all workspace dependencies)
• No .gitignore needed: worktrees are outside repo directory

Common Mistakes

Confusing knowledge base structure with repo structure

• Problem: KB uses changelogs/apps/<app>/<issue>/ but repo uses apps/<app>/changelog/<issue>/
• Fix: In worktrees, always use repo pattern: $CHANGELOG_FOLDER/changelog/$BRANCH_NAME/
• Example: .claude folder → .claude/changelog/pnx-050-feature/ (NOT changelogs/.claude/)

Wrong changelog path structure

• Problem: Creating changelogs/$FOLDER/ instead of $FOLDER/changelog/$BRANCH/
• Fix: Pattern is ALWAYS <folder>/changelog/<branch>/ - "changelog" (singular) is a subdirectory

Forgetting pnpm install

• Problem: Missing dependencies, confusing build errors
• Fix: Always run pnpm install after worktree creation (this skill does it automatically)

Skipping changelog folder setup

• Problem: Worktree has no project context, /pr-resume and hooks don't work
• Fix: Always ask for and create changelog structure with current-project.txt

Removing worktree with uncommitted changes

• Problem: Lost work
• Fix: Check status first, block removal if changes exist

Deleting unmerged branches

• Problem: Lost commits not on any branch
• Fix: Check merge status, require explicit confirmation for unmerged

Running npm instead of pnpm

• Problem: Wrong lockfile, dependency conflicts
• Fix: Always use pnpm in this monorepo

Creating worktree inside repo

• Problem: Git tracking conflicts, .gitignore issues
• Fix: Always use ../YourProject-Worktrees location

Example Workflows

Starting New Feature Work

User: Create a worktree for auth-refactor

Claude: I'm using the git-worktrees skill to create a worktree.

Branch `carlos/auth-refactor` doesn't exist. Create from `main`? (Y/n)

User: Y

Claude: Which folder should contain the changelog for this work?

Examples:
  - .claude (for cross-cutting work)
  - apps/website (for website changes)
  - apps/backend (for backend changes)

User: apps/website

Claude: [Creates worktree]
[Runs pnpm install - 2m 34s]
[Creates apps/website/changelog/auth-refactor/]
[Creates CHANGELOG.md and PLAN.md]
[Creates .claude/current-project.txt]

Worktree created:
  Branch: carlos/auth-refactor
  Path: ../YourProject-Worktrees/carlos/auth-refactor
  Changelog: apps/website/changelog/auth-refactor
  Dependencies: installed

To work in this worktree, start a new Claude session in:
  cd ../YourProject-Worktrees/carlos/auth-refactor

Creating Worktree with Changelog Folder Specified

User: Create a worktree for pnx-350-fix-player in packages/mylib

Claude: I'm using the git-worktrees skill to create a worktree.

Branch `carlos/pnx-350-fix-player` doesn't exist. Create from `main`? (Y/n)

User: Y

Claude: [Creates worktree]
[Runs pnpm install]
[Creates packages/mylib/changelog/pnx-350-fix-player/]

Worktree created:
  Branch: carlos/pnx-350-fix-player
  Path: ../YourProject-Worktrees/carlos/pnx-350-fix-player
  Changelog: packages/mylib/changelog/pnx-350-fix-player
  Dependencies: installed

Checking Active Worktrees

User: List my worktrees

Claude: I'm using the git-worktrees skill to list worktrees.

Worktrees:
  carlos/auth-refactor
    Path: ../YourProject-Worktrees/carlos/auth-refactor
    Changelog: apps/website/changelog/auth-refactor
    Status: clean
    Behind main: 0 commits

  carlos/fix-player-seeking
    Path: ../YourProject-Worktrees/carlos/fix-player-seeking
    Changelog: packages/mylib/changelog/fix-player-seeking
    Status: 2 uncommitted changes
    Behind main: 5 commits

Cleaning Up After PR Merge

User: Remove the auth-refactor worktree

Claude: I'm using the git-worktrees skill to remove a worktree.

[Checking for uncommitted changes... none found]
[Removing worktree...]

Branch `carlos/auth-refactor` is merged into main. Delete it? (Y/n)

User: Y

Claude: [Deletes local branch]
[Deletes remote branch]
[Cleans empty directories]

Worktree removed:
  Path: ../YourProject-Worktrees/carlos/auth-refactor
  Branch: deleted (was merged)
  Cleanup: complete

Red Flags

Never:

• Remove worktree with uncommitted changes
• Delete unmerged branch without explicit confirmation
• Skip pnpm install after creation
• Skip changelog folder setup
• Create worktrees inside the main repo
• Use npm instead of pnpm

Always:

• Use the ../YourProject-Worktrees location
• Preserve branch hierarchy in path
• Ask for changelog folder if not specified
• Create .claude/current-project.txt in worktree
• Run pnpm install after creation
• Check merge status before offering branch deletion
• Report full path for new session

Integration

Pairs with:

• /pr-start - Similar changelog structure, but for main repo branches
• /pr-resume - Uses .claude/current-project.txt to find changelog
• /pr-summary - Reads from changelog location
• Implementation planning - create worktree before executing plans
• Any multi-branch development work