Worktree

User: /worktree create auth-refactor

Claude: Creating worktree for auth-refactor...

# Step 1: Verify we're in a git repo and check current state
$ git rev-parse --is-inside-work-tree
true

$ git worktree list
/Users/dev/myapp  abc1234 [main]

# Step 2: Check if branch already exists
$ git branch --list 'feat/auth-refactor'
(no output = branch doesn't exist, safe to proceed)

# Step 3: Create the worktree with new branch
$ git worktree add .worktrees/auth-refactor -b feat/auth-refactor
Preparing worktree (new branch 'feat/auth-refactor')
HEAD is now at abc1234 feat: add user dashboard

# Step 4: Copy environment files
$ cp .env .worktrees/auth-refactor/ 2>/dev/null && echo "Copied .env" || echo "No .env found"
Copied .env

$ cp .nvmrc .worktrees/auth-refactor/ 2>/dev/null && echo "Copied .nvmrc" || echo "No .nvmrc found"
Copied .nvmrc

# Step 5: Detect package manager and install
$ ls .worktrees/auth-refactor/package-lock.json
.worktrees/auth-refactor/package-lock.json

$ cd .worktrees/auth-refactor && npm install
added 847 packages in 32s

# Step 6: Ensure .worktrees/ is in .gitignore
$ grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
(added to .gitignore)

# Step 7: Verify worktree is functional
$ git -C .worktrees/auth-refactor status
On branch feat/auth-refactor
nothing to commit, working tree clean

$ git worktree list
/Users/dev/myapp                      abc1234 [main]
/Users/dev/myapp/.worktrees/auth-refactor  abc1234 [feat/auth-refactor]

Worktree created successfully.

Location: .worktrees/auth-refactor
Branch:   feat/auth-refactor
Base:     main (abc1234)

Environment files copied:
  - .env
  - .nvmrc

Dependencies installed via npm.

To work in this worktree:
  cd .worktrees/auth-refactor

To open in new terminal/editor:
  code .worktrees/auth-refactor

User: /worktree list

Claude: Current worktrees:

$ git worktree list
/Users/dev/myapp                          abc1234 [main]
/Users/dev/myapp/.worktrees/auth-refactor def5678 [feat/auth-refactor]
/Users/dev/myapp/.worktrees/api-cache     ghi9012 [feat/api-cache]

Active Worktrees:

1. main (primary)
   Path:   /Users/dev/myapp
   Commit: abc1234

2. auth-refactor
   Path:   .worktrees/auth-refactor
   Branch: feat/auth-refactor
   Commit: def5678

3. api-cache
   Path:   .worktrees/api-cache
   Branch: feat/api-cache
   Commit: ghi9012

User: /worktree remove auth-refactor

Claude: Checking worktree status before removal...

# Step 1: Check for uncommitted changes
$ git -C .worktrees/auth-refactor status --porcelain
 M src/auth/login.ts
?? src/auth/temp.ts

# Step 2: Check for unpushed commits
$ git -C .worktrees/auth-refactor log origin/feat/auth-refactor..HEAD --oneline 2>/dev/null || git -C .worktrees/auth-refactor log origin/main..HEAD --oneline
a1b2c3d feat(auth): add session validation
d4e5f6g feat(auth): refactor token storage

WARNING: This worktree has uncommitted changes:

Modified:  src/auth/login.ts
Untracked: src/auth/temp.ts

WARNING: This worktree has 2 unpushed commits:

a1b2c3d feat(auth): add session validation
d4e5f6g feat(auth): refactor token storage

Are you sure you want to remove this worktree?
This will DELETE all uncommitted changes permanently.

Options:
1. Commit and push changes first, then remove
2. Force remove (loses uncommitted changes)
3. Cancel

User: force remove, I don't need those changes

Claude: Removing worktree...

# Step 3: Force remove the worktree
$ git worktree remove .worktrees/auth-refactor --force
Removing worktree directory .worktrees/auth-refactor

# Step 4: Ask about branch deletion

Worktree removed.

The branch 'feat/auth-refactor' still exists with 2 commits.
Delete the branch as well? (y/n)

User: yes

Claude: Deleting branch...

$ git branch -D feat/auth-refactor
Deleted branch feat/auth-refactor (was a1b2c3d).

$ git worktree list
/Users/dev/myapp                      abc1234 [main]
/Users/dev/myapp/.worktrees/api-cache ghi9012 [feat/api-cache]

Cleanup complete.
- Worktree directory removed
- Branch feat/auth-refactor deleted

$ git worktree add .worktrees/auth-feature -b feat/auth-feature
fatal: a branch named 'feat/auth-feature' already exists

# Option 1: Use existing branch (if worktree doesn't exist for it)
$ git worktree add .worktrees/auth-feature feat/auth-feature

# Option 2: Choose a different name
$ git worktree add .worktrees/auth-feature-v2 -b feat/auth-feature-v2

# Option 3: Delete the old branch first (if safe)
$ git branch -d feat/auth-feature  # safe delete (fails if unmerged)
$ git worktree add .worktrees/auth-feature -b feat/auth-feature

$ git worktree add .worktrees/auth-feature -b feat/auth-feature
fatal: '.worktrees/auth-feature' already exists

# Check if it's a valid worktree
$ git worktree list | grep auth-feature

# If listed: worktree exists, inform user
# If not listed: orphaned directory, safe to remove
$ rm -rf .worktrees/auth-feature
$ git worktree prune
$ git worktree add .worktrees/auth-feature -b feat/auth-feature

$ cd .worktrees/auth-feature && npm install
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! peer dep missing: react@^17.0.0

# Worktree is created but deps failed
# Option 1: Try with legacy peer deps
$ cd .worktrees/auth-feature && npm install --legacy-peer-deps

# Option 2: Use different package manager
$ cd .worktrees/auth-feature && yarn install

# Option 3: Skip install, let user handle

$ cd .worktrees/auth-feature && npm install
npm ERR! code ENOSPC
npm ERR! syscall write
npm ERR! errno -28
npm ERR! ENOSPC: no space left on device

# Clean up the partial worktree
$ git worktree remove .worktrees/auth-feature --force
$ git branch -D feat/auth-feature

# Check disk space
$ df -h .

$ git worktree add ".worktrees/my feature" -b "feat/my feature"
fatal: 'feat/my feature' is not a valid branch name

# Valid patterns: alphanumeric, hyphens, underscores
# Invalid: spaces, special chars, starting with hyphen

# Sanitize input
name="my feature"
sanitized=$(echo "$name" | tr ' ' '-' | tr -cd 'a-zA-Z0-9-_')
# Result: my-feature

$ git worktree remove .worktrees/auth-feature
fatal: '.worktrees/auth-feature' is locked

# Check why it's locked
$ cat .git/worktrees/auth-feature/locked
Process still running or editor has files open

# Unlock if safe
$ git worktree unlock .worktrees/auth-feature
$ git worktree remove .worktrees/auth-feature

# 1. Remove node_modules if install started
$ rm -rf .worktrees/<name>/node_modules 2>/dev/null

# 2. Remove the worktree directory
$ git worktree remove .worktrees/<name> --force 2>/dev/null || rm -rf .worktrees/<name>

# 3. Prune worktree references
$ git worktree prune

# 4. Delete the branch if it was created
$ git branch -D feat/<name> 2>/dev/null

# 5. Verify clean state
$ git worktree list
$ git branch --list 'feat/<name>'

cleanup_failed_worktree() {
    local name="$1"
    rm -rf ".worktrees/${name}/node_modules" 2>/dev/null
    git worktree remove ".worktrees/${name}" --force 2>/dev/null || rm -rf ".worktrees/${name}"
    git worktree prune
    git branch -D "feat/${name}" 2>/dev/null
    echo "Cleaned up failed worktree: ${name}"
}