Finish Worktree

Complete work in a worktree and clean up.

Arguments

•--pr - Create a pull request (default)
•--merge - Direct merge to target branch
•--force - Force cleanup with uncommitted changes

Pre-Completion Checklist

Before finishing, verify:

• All changes committed
• Tests passing
• Branch pushed to remote
• Work reviewed (if applicable)

bash

# Check for uncommitted changes
git status

# Run tests
npm test  # or your test command

# Push if needed
git push -u origin $(git branch --show-current)

Option 1: Create Pull Request (--pr)

For peer workflows and standard code review.

Step 1: Ensure Up to Date

bash

# Fetch latest changes
git fetch origin main

# Rebase to include latest main
git rebase origin/main

# Force push rebased branch
git push --force-with-lease

Step 2: Create PR

bash

gh pr create \
  --base main \
  --title "feat: <description>" \
  --body "## Summary
<What this PR accomplishes>

## Changes
- <Bullet list of changes>

## Testing
<How to test>
"

Step 3: After PR Merge

bash

# Return to main project directory
cd ../..  # Exit .worktrees/<name> to project root

# Pull merged changes
git checkout main
git pull origin main

# Remove worktree
git worktree remove .worktrees/<name>

# Delete local branch if still exists (PR merge usually deletes remote)
git branch -d feature/<name> 2>/dev/null

# Prune stale references
git worktree prune

Option 2: Direct Merge (--merge)

For orchestrator integration where work merges directly.

Step 1: Switch to Target Branch

bash

# From main project directory (not worktree)
cd /path/to/main/project
git checkout <target-branch>

Step 2: Merge Worktree Branch

bash

git merge feature/<name> --no-ff -m "Merge <description>"

Step 3: Run Tests

bash

npm test  # Verify integration

Step 4: Cleanup

bash

# Remove worktree
git worktree remove .worktrees/<name>

# Delete local branch
git branch -d feature/<name>

# If pushed to remote, delete remote branch
git push origin --delete feature/<name>

# Prune stale references
git worktree prune

Force Cleanup (--force)

When worktree has uncommitted changes and you want to discard:

bash

# Force remove worktree (discards all uncommitted changes!)
git worktree remove --force .worktrees/<name>

# Delete branch
git branch -D feature/<name>

# Prune
git worktree prune

Warning: --force discards uncommitted work permanently.

Complete Cleanup Script

For cleaning up multiple worktrees:

bash

#!/bin/bash
# cleanup-worktree.sh <worktree-name>

NAME=$1
BRANCH="feature/${NAME}"
WORKTREE=".worktrees/${NAME}"

# Check if worktree exists
if git worktree list | grep -q "$WORKTREE"; then
    # Remove worktree
    git worktree remove "$WORKTREE" || git worktree remove --force "$WORKTREE"
fi

# Delete local branch
git branch -d "$BRANCH" 2>/dev/null || git branch -D "$BRANCH" 2>/dev/null

# Delete remote branch if exists
git push origin --delete "$BRANCH" 2>/dev/null

# Prune
git worktree prune

echo "Cleanup complete for $NAME"

Verification

After cleanup:

bash

# Verify worktree removed
git worktree list

# Verify branch deleted
git branch -a | grep <name>

# Should show no results for worktree or branch

Troubleshooting

Cannot Remove: Uncommitted Changes

Error: fatal: cannot remove worktree with uncommitted changes

Solutions:

•Commit your changes: git add . && git commit -m "WIP"
•Stash changes: git stash
•Force remove (loses changes): git worktree remove --force .worktrees/<name>

Cannot Remove: Worktree Locked

Error: fatal: worktree is locked

Solution:

bash

git worktree unlock .worktrees/<name>
git worktree remove .worktrees/<name>

Branch Cannot Be Deleted

Error: error: branch is not fully merged

Solutions:

•If work is merged via PR, force delete: git branch -D feature/<name>
•If work needs preserving, merge first

Stale Worktree Entry

If worktree directory was manually deleted:

bash

git worktree prune

Quick Reference

Task	Command
Remove worktree	`git worktree remove .worktrees/<name>`
Force remove	`git worktree remove --force .worktrees/<name>`
Delete local branch	`git branch -d feature/<name>`
Force delete branch	`git branch -D feature/<name>`
Delete remote branch	`git push origin --delete feature/<name>`
Prune stale entries	`git worktree prune`
Create PR	`gh pr create --base main`
Merge PR	`gh pr merge --squash --delete-branch`