Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ahmadawais/gwtree/llms.txt

Use this file to discover all available pages before exploring further.

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:
3
  • The worktree exists for the current repo
  • The worktree directory is still present
    • 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:
    9
  • Commit the changes: cd ../myrepo-feature-auth && git add . && git commit
  • Stash the changes: cd ../myrepo-feature-auth && git stash
    • 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:
    22
  • git worktree remove "{path}" --force
  • Falls back to rm -rf if needed
  • Removes from GWTree tracking database
    • 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:
    14
  • git worktree remove "{path}" --force
  • Falls back to rm -rf if needed
  • Removes from tracking database

    • ​
    No Worktrees to Clean

    If no worktrees match the criteria: 
    ┌  Clean Merged Worktrees
│
└  No worktrees to clean
    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

    CommandPurposeRemovesMergesDeletes Branch
    gwt merge <name>Merge specific worktreeYesYesYes
    gwt cleanRemove merged worktreesYesNoNo
    gwt clean --allRemove all worktreesYesNoNo
    gwt rmManually remove worktreesYesNoNo

    ​
    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

    Build docs developers (and LLMs) love

    Get started for freeTalk to us