Merging and Cleanup

Merge completed work and clean up worktrees

GWTree provides commands to merge your work back to the main branch and automatically clean up worktrees when they’re no longer needed.

Merge Command

Merge a worktree’s branch to main and remove the worktree:

gwt merge <name>
# or
gwt m <name>

Finding Worktrees by Name

The merge command accepts different name formats:

# By branch name
gwt merge feature-auth

# By worktree directory name
gwt merge myrepo-feature-auth

# By worktree suffix
gwt merge feature-auth

GWTree searches for matches in this order:

1. Exact branch name match
2. Worktree directory name match
3. Worktree suffix match (without repo prefix)

Merge Workflow

1. Step 1: Validate Worktree
2. GWTree verifies:
4. ┌  Merge feature-auth to main
   

5. Step 2: Check for Uncommitted Changes
6. The merge command requires a clean working directory:
7. # If changes exist
   ✖ Worktree has uncommitted changes. Commit or stash them first.
   

8. You must either:
10. Step 3: Switch to Main
11. GWTree switches the main repository to the main branch:
12. │
    │  ◆  Switch  git checkout main
    │  └  switched to main
    

13. This runs git checkout main in the repository root (not the worktree).
14. Step 4: Merge Branch
15. The worktree’s branch is merged into main:
16. │
    │  ◆  Merge  git merge feature-auth
    │  └  merged to main
    

17. Runs git merge feature-auth in the main repository.
18. Step 5: Remove Worktree
19. The worktree directory is removed:
20. │
    │  ◆  Remove  git worktree remove .../myrepo-feature-auth
    │  └  worktree removed
    

21. Executes:
23. Step 6: Delete Branch
24. The feature branch is deleted:
25. │
    │  ◆  Branch  git branch -d feature-auth
    │  └  branch deleted
    │
    └  Done  Merged and cleaned up feature-auth
    

26. Runs git branch -d feature-auth to clean up the branch.

Merge Failures

Uncommitted Changes

$ gwt merge feature-auth
✖ Worktree has uncommitted changes. Commit or stash them first.

Solution: Commit or stash changes before merging.

Merge Conflicts

│
│  ◆  Merge  git merge feature-auth
│  └  CONFLICT (content): Merge conflict in src/app.ts
│
✖ Merge failed. Resolve conflicts manually.

Solution:

1. The main repository is left in a conflicted state
2. Navigate to the main repo
3. Resolve conflicts manually
4. Complete the merge with git commit
5. Remove the worktree manually with gwt rm

Clean Command

Automatically remove worktrees that have been merged to main:

gwt clean
# or
gwt c

Clean Merged Worktrees

By default, gwt clean removes only merged worktrees:

┌  Clean Merged Worktrees
│
│  Will remove:
│  •  bug-fix myrepo-bug-fix
│  •  feature-old myrepo-feature-old
│
◆  Remove 2 worktrees? (Y/n)

How Merge Detection Works

GWTree determines if a worktree is merged by running:

git branch --merged main

A worktree is considered merged if its branch appears in this list.

Clean All Worktrees

Remove ALL worktrees regardless of merge status:

gwt clean --all
# or
gwt clean -a

┌  Clean All Worktrees
│
│  Will remove:
│  •  feature-auth myrepo-feature-auth
│  •  feature-api myrepo-feature-api
│  •  bug-fix myrepo-bug-fix
│
◆  Remove 3 worktrees? (Y/n)

Using --all removes worktrees even if they have:

• Uncommitted changes
• Unpushed commits
• Unmerged work

Make sure to review your worktrees with gwt status first.

Clean Workflow

1. Step 1: Scan Worktrees
2. GWTree scans all worktrees for the current repo and checks their merge status.
3. Step 2: Show Preview
4. Lists all worktrees that will be removed:
5. │  Will remove:
   │  •  bug-fix myrepo-bug-fix
   │  •  feature-old myrepo-feature-old
   

6. Step 3: Confirm
7. Prompts for confirmation:
8. ◆  Remove 2 worktrees? (Y/n)
   

9. Cancelling exits without removing anything.
10. Step 4: Remove Each Worktree
11. For each worktree:
12. │
    │  ◆  Removed myrepo-bug-fix
    │  └  /path/to/parent/myrepo-bug-fix
    │
    │  ◆  Removed myrepo-feature-old
    │  └  /path/to/parent/myrepo-feature-old
    │
    └  Done  Removed 2 worktrees
    

13. Removal steps:

No Worktrees to Clean

If no worktrees match the criteria:

┌  Clean Merged Worktrees
│
└  No worktrees to clean

Recommended Workflow

Combine commands for an efficient workflow:

1. Check Status

See which worktrees are ready:

gwt status

Output:

│  ◆  feature-auth  +245 -12
│  └  ready to merge (3 commits ahead)
│
│  ◆  feature-api  +89 -5
│  └  2 changed, 1 ahead
│
│  ◆  bug-fix
│  └  ✓ merged
│
└  1 ready to merge, 1 in progress, 1 merged

2. Merge Ready Worktrees

Merge worktrees that are ready:

gwt merge feature-auth

This:

• Merges the branch to main
• Removes the worktree
• Deletes the branch

3. Clean Up Merged Worktrees

Remove any remaining merged worktrees:

gwt clean

This removes worktrees that were merged elsewhere (like through PRs).

4. Continue Working

Focus on in-progress worktrees:

gwt status

Output:

│  ◆  feature-api  +89 -5
│  └  2 changed, 1 ahead
│
└  1 in progress

Examples

Merge Single Worktree

# Complete your work
cd ../myrepo-feature-auth
git add .
git commit -m "Complete feature"

# Merge to main
cd ../myrepo
gwt merge feature-auth

Clean After PR Merges

After merging PRs on GitHub:

cd myrepo
git pull origin main
gwt clean

This removes local worktrees whose branches were merged remotely.

Emergency Cleanup

Remove all worktrees quickly:

gwt clean --all

This removes all worktrees including those with uncommitted changes.

Selective Merge

# Check what's ready
gwt status

# Merge only completed work
gwt merge feature-auth
gwt merge bug-fix

# Keep working on others

Comparison Table

Command	Purpose	Removes	Merges	Deletes Branch
gwt merge <name>	Merge specific worktree	Yes	Yes	Yes
gwt clean	Remove merged worktrees	Yes	No	No
gwt clean --all	Remove all worktrees	Yes	No	No
gwt rm	Manually remove worktrees	Yes	No	No

When to Use Each Command

Use gwt merge when:

• You’re ready to merge work to main
• You want to merge and clean up in one step
• You’re working with local branches (no PR)
• You want the branch deleted automatically

Use gwt clean when:

• Branches were merged via pull requests
• You have multiple merged worktrees to remove
• You want to preview before removing
• You want to clean up old worktrees

Use gwt rm when:

• You want to abandon work without merging
• You need fine-grained control over removal
• You want to remove specific worktrees
• You want to search and select interactively

Next Steps

• Learn about configuration to customize behavior
• Review managing worktrees for tracking commands
• Return to creating worktrees to start new work