Skip to main content

​
Syntax

gwt merge <name>
gwt m <name>

​
Description

Merges a worktree’s branch into main and removes both the worktree and the branch. This is a complete cleanup operation for finished work. The command performs all steps needed to complete a feature:
  1. Switches to main branch
  2. Merges the worktree branch
  3. Removes the worktree
  4. Deletes the branch

​
Arguments

​
name
string
required
Name of the worktree to merge. Can be:
  • Branch name (e.g., feature-auth)
  • Worktree directory name (e.g., myapp-feature-auth)
  • Worktree suffix (e.g., feature-auth for myapp-feature-auth)

​
Aliases

  • m - Short alias for merge

​
Workflow

┌  Merge feature-auth to main
│
│  ◆  Switch  git checkout main
│  └  switched to main
│
│  ◆  Merge  git merge feature-auth
│  └  merged to main
│
│  ◆  Remove  git worktree remove .../myapp-feature-auth
│  └  worktree removed
│
│  ◆  Branch  git branch -d feature-auth
│  └  branch deleted
│
└  Done  Merged and cleaned up feature-auth

​
Examples

​
Merge by branch name

gwt merge feature-auth

​
Merge by worktree name

gwt merge myapp-feature-auth

​
Merge by suffix

# For worktree: myapp-feature-auth
gwt merge feature-auth

​
Using short alias

gwt m feature-payment

​
Prerequisites

The worktree must have: ✅ No uncommitted changes - All changes must be committed 
# Check status first
gwt status

# If there are changes, commit them
cd ../myapp-feature-auth
git add .
git commit -m "Complete feature"

# Then merge
gwt merge feature-auth

​
Error Handling

​
Uncommitted Changes

If the worktree has uncommitted changes: 
┌  Merge feature-auth to main
│
✖  Worktree has uncommitted changes. Commit or stash them first.
Solution: 
cd ../myapp-feature-auth
git add .
git commit -m "Final changes"
gwt merge feature-auth

​
Merge Conflicts

If the merge has conflicts: 
│  ◆  Switch  git checkout main
│  └  switched to main
│
│  ◆  Merge  git merge feature-auth
│  └  CONFLICT (content): Merge conflict in src/app.ts
│
✖  Merge failed. Resolve conflicts manually.
Solution: 
# You're now on main with conflicts
git status

# Resolve conflicts in your editor
# Then:
git add .
git commit

# Manually remove the worktree
gwt remove

​
Worktree Not Found

✖  Worktree not found: feature-xyz
Check available worktrees: 
gwt list

​
Merge Process Details

​
Step 1: Switch to Main

Switches the main repository to the main branch: 
git checkout main

​
Step 2: Merge Branch

Merges the worktree’s branch into main: 
git merge feature-auth
This performs a standard git merge. If fast-forward is possible, it does a fast-forward merge. Otherwise, it creates a merge commit.

​
Step 3: Remove Worktree

Removes the worktree directory: 
git worktree remove "<path>" --force
Also removes the entry from GWTree’s registry.

​
Step 4: Delete Branch

Deletes the feature branch: 
git branch -d feature-auth
Uses -d (safe delete) which prevents deletion if branch isn’t fully merged.

​
Name Resolution

The <name> argument is flexible and matches: 
# All these work for worktree "myapp-feature-auth" with branch "feature-auth":
gwt merge feature-auth
gwt merge myapp-feature-auth
For worktree myapp-feat with branch feature/auth-impl: 
gwt merge feature/auth-impl    # Branch name
gwt merge myapp-feat           # Worktree directory name
gwt merge feat                 # Suffix

​
When to Use

​
Local Development

Merge completed features directly: 
# Feature complete
gwt merge feature-auth

# Continue with next feature
gwt feature-payment

​
After PR Merge

If your feature was merged via GitHub PR, you should:
  1. Pull the merged changes: git pull
  2. Just remove the worktree: gwt clean or gwt remove
Do NOT use gwt merge as the branch is already merged.

​
Hotfixes

Quickly merge urgent fixes: 
# Create fix
gwt hotfix-123
cd ../myapp-hotfix-123
# ... make changes ...
git commit -am "Fix critical bug"

# Merge immediately
gwt merge hotfix-123

​
Comparison with Manual Process

​
Using gwt merge

gwt merge feature-auth

​
Manual equivalent

cd main-repo
git checkout main
git merge feature-auth
git worktree remove ../myapp-feature-auth --force
git branch -d feature-auth
rm -rf ../myapp-feature-auth
# Edit ~/.gwtree/worktrees.json manually

​
Integration with PR Workflow

​
GitHub/GitLab Merge

# 1. Push branch
cd ../myapp-feature-auth
git push origin feature-auth

# 2. Create and merge PR on GitHub

# 3. Pull merged changes
cd main-repo
git pull

# 4. Clean up worktree (don't merge again!)
gwt clean

​
Local Merge

# 1. Ensure feature is complete
gwt status

# 2. Merge locally
gwt merge feature-auth

# 3. Push to remote
git push origin main

​
Exit Codes

  • 0 - Success (branch merged, worktree removed, branch deleted)
  • 1 - Error (worktree not found, uncommitted changes, merge conflict, not in git repository)