Managing Worktrees

List, view status, and remove git worktrees

GWTree provides powerful commands to manage your worktrees throughout their lifecycle.

List Worktrees

View all worktrees for the current repository:

gwt ls
# or
gwt list

List Output

┌  Worktrees for myrepo
│
│  ◆  feature-auth
│  └  /path/to/parent/myrepo-feature-auth
│
│  ◆  feature-api
│  └  /path/to/parent/myrepo-feature-api
│
│  ◆  bug-fix
│  └  /path/to/parent/myrepo-bug-fix
│
└  3 worktrees

The list shows:

• Branch name: The git branch for the worktree
• Path: Full filesystem path to the worktree directory
• Count: Total number of worktrees

Empty List

If no worktrees exist for the repo:

No worktrees found for this repo

View Status

Get detailed status information for all worktrees:

gwt status
# or
gwt st

Status Output

┌  Status for myrepo
│
│  ◆  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

Status Information

For each worktree, the status command shows:

Change Statistics

• Additions: Lines added (+245)
• Deletions: Lines removed (-12)
• Calculated from git diff --stat HEAD

Commit Position

• Ahead: Commits ahead of main
• Behind: Commits behind main
• Calculated from git rev-list --left-right --count main...branch

Work Status

• Changed files: Uncommitted modifications
• Calculated from git status --porcelain

Merge Status

• ✓ merged: Branch has been merged to main
• ready to merge: No uncommitted changes, commits ahead
• in progress: Has uncommitted changes or needs sync

Status Categories

Ready to Merge

Indicators:

• Green color
• Shows “ready to merge (N commits ahead)”
• No uncommitted changes
• Commits exist ahead of main

Example:

│  ◆  feature-auth  +245 -12
│  └  ready to merge (3 commits ahead)

Actions:

• Ready for code review
• Can be merged with gwt merge feature-auth
• Can be cleaned up with gwt clean after merging

In Progress

Indicators:

• Yellow color
• Shows changed files and/or commit position
• Has uncommitted changes or unpushed commits

Example:

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

Status details:

• 2 changed: 2 files with uncommitted changes
• 1 ahead: 1 commit ahead of main
• 3 behind: 3 commits behind main (need to rebase)

Actions:

• Continue development
• Commit changes
• Rebase if behind

Merged

Indicators:

• Gray color
• Shows ”✓ merged”
• Branch has been merged to main

Example:

│  ◆  bug-fix
│  └  ✓ merged

Actions:

• Can be safely removed with gwt clean
• Worktree is no longer needed

Status Summary

The bottom line shows aggregated counts:

└  1 ready to merge, 2 in progress, 1 merged

Helps you quickly understand:

• How many worktrees are ready for review/merge
• How many are actively being worked on
• How many can be cleaned up

Remove Worktrees

Interactively remove worktrees:

gwt rm
# or
gwt remove

Remove Workflow

Remove Multiple Worktrees

The remove command continues in a loop, allowing you to remove multiple worktrees without restarting:

1. Select and remove first worktree
2. List automatically refreshes
3. Select and remove next worktree
4. Repeat until done
5. Cancel to exit

Force Removal

The --force flag ensures removal even if:

• The worktree has uncommitted changes
• The worktree has unpushed commits
• The git repository is in an inconsistent state

If git worktree remove fails, GWTree falls back to rm -rf to delete the directory.

Worktree Tracking

GWTree maintains a global database of worktrees at:

~/.gwtree/worktrees.json

Tracked Information

For each worktree:

{
  "path": "/path/to/parent/myrepo-feature-auth",
  "branch": "feature-auth",
  "repoRoot": "/path/to/parent/myrepo",
  "repoName": "myrepo",
  "createdAt": "2024-02-28T10:30:00.000Z"
}

Per-Repository Filtering

All commands (list, status, rm) automatically:

1. Detect the current repository
2. Filter worktrees to show only those for the current repo
3. Verify worktree directories still exist

This means:

• You can have worktrees for multiple repos
• Each repo only sees its own worktrees
• Deleted directories are automatically excluded

Examples

Check What Needs Attention

cd ~/projects/myrepo
gwt status

Review the status to see:

• Which worktrees are ready to merge
• Which worktrees have uncommitted work
• Which worktrees can be cleaned up

List All Worktrees

gwt ls

Simple list of branches and paths.

Remove Old Worktrees

gwt rm
# Type "feature-old" to search
# Confirm removal
# Continue removing others or cancel

Clean Up After Work

# Check status
gwt status

# Merge completed work
gwt merge feature-auth

# Clean up merged worktrees
gwt clean

Comparison Table

Command	Purpose	Output	Interactive
gwt ls	List worktrees	Branch + path	No
gwt status	Detailed status	Changes, commits, merge state	No
gwt rm	Remove worktrees	Confirmation prompts	Yes

Next Steps

• Learn about merging and cleanup for completing work
• Explore configuration to customize behavior
• Return to creating worktrees for starting new work