repo wt clean

​

Syntax

repo wt clean

​

Arguments

​

Behavior

​

1. Repository and Default Branch Detection

• Locates the repository root
• Accesses the bare repository at .bare/
• Detects the default branch (main/master) automatically

​

2. Worktree Discovery

• Queries Git for complete worktree list
• Parses worktree information line by line
• Processes each worktree for potential removal

​

3. Worktree Filtering

• The .bare/ directory itself is a “worktree” in Git’s view
• Never attempts to remove the bare repository
• Continues to next worktree

• Identifies worktree by directory basename
• If basename matches default branch name, skips it
• Ensures default branch worktree is always preserved

​

4. Removal Attempt

• Displays message indicating removal attempt
• Executes git worktree remove on the path
• Suppresses error output to keep display clean

​

5. Error Handling

• Displays warning (does not abort the command)
• Indicates the worktree may have uncommitted changes
• Continues processing remaining worktrees

​

6. Cleanup and Verification

• Runs git worktree prune to clean up stale references
• Displays remaining worktrees with repo wt list
• Shows final state of the repository

​

Examples

​

Clean All Feature Branches

# Before clean
repo wt list
# Output:
# /path/to/repo/.bare           (bare)
# /path/to/repo/main            abc1234 [main]
# /path/to/repo/feature-a       def5678 [feature-a]
# /path/to/repo/feature-b       ghi9012 [feature-b]
# /path/to/repo/fix-bug         jkl3456 [fix-bug]

repo wt clean
# Output:
# Removing worktree: /path/to/repo/feature-a
# Removing worktree: /path/to/repo/feature-b
# Removing worktree: /path/to/repo/fix-bug
# Clean complete. Remaining worktrees:
# /path/to/repo/.bare           (bare)
# /path/to/repo/main            abc1234 [main]

​

Clean with Protected Worktrees

# One worktree has uncommitted changes
repo wt clean

# Output:
# Removing worktree: /path/to/repo/feature-a
# Removing worktree: /path/to/repo/feature-b
#   Warning: Could not remove /path/to/repo/feature-b (may have uncommitted changes)
# Removing worktree: /path/to/repo/fix-bug
# Clean complete. Remaining worktrees:
# /path/to/repo/.bare           (bare)
# /path/to/repo/main            abc1234 [main]
# /path/to/repo/feature-b       ghi9012 [feature-b]

​

Post-Sprint Cleanup

# After merging all feature branches
git checkout main
git pull

# Clean up all feature worktrees at once
repo wt clean

# Only main worktree remains

​

Verify Before Cleaning

# Check what will be removed
repo wt list

# Run clean
repo wt clean

# Verify results
repo wt list

​

What Gets Removed?

• All feature branch worktrees
• All bugfix branch worktrees
• PR review worktrees
• Any non-default branch worktrees

• The bare repository (.bare/)
• The default branch worktree (main/master)
• Worktrees with uncommitted changes (protected by Git)

​

Error Cases

​

Repository Root Not Found

# Running outside a repository
repo wt clean

# Output:
# Error: Not in a repo-managed repository

​

Worktrees with Uncommitted Changes

repo wt clean

# Output:
# Removing worktree: /path/to/repo/feature-a
#   Warning: Could not remove /path/to/repo/feature-a (may have uncommitted changes)

1. Commit changes: cd <worktree> && git commit -am "Save work"
2. Stash changes: cd <worktree> && git stash
3. Remove manually with force: repo wt rm <branch> then force remove if needed

​

No Worktrees to Clean

repo wt clean

# Output:
# Clean complete. Remaining worktrees:
# /path/to/repo/.bare           (bare)
# /path/to/repo/main            abc1234 [main]

​

Tips and Best Practices

​

When to Use Clean

• After completing a sprint or milestone
• After merging multiple feature branches
• Before starting new work
• When switching between major project phases
• Periodically to free up disk space

​

Safe by Default

• Cannot remove default branch
• Cannot remove worktrees with uncommitted work
• Continues on errors rather than aborting
• Shows what remains after cleaning

​

Commit Before Cleaning

# Check each worktree for uncommitted changes
repo wt list | while read -r wt; do
  cd "$wt" && git status --short
done

# Commit or stash as needed

# Then clean
repo wt clean

​

Selective Removal

# Use 'repo wt rm' for selective removal instead
repo wt rm feature-a
repo wt rm feature-b
# feature-c remains

​

Default Branch Detection

• main or master as default
• Uses Git’s HEAD reference on origin
• Respects your repository’s convention

​

Post-Clean Actions

• Runs git worktree prune to remove stale administrative data
• Displays remaining worktrees for verification
• Ensures your repository state is clean and consistent

​

Disk Space Recovery

• Removes working directory files
• Keeps Git history (in bare repo)
• Each worktree can be several hundred MB
• Useful for large codebases

​

Integration with Git Workflow

# Create worktrees for features
repo wt add feature-a
repo wt add feature-b
repo wt add feature-c

# Work on features...

# Merge all to main
repo wt go main
gh pr merge 101
gh pr merge 102
gh pr merge 103

# Clean up all feature worktrees
repo wt clean

​

Manual Override

# Navigate to the worktree
cd /path/to/worktree

# Force remove (WARNING: loses uncommitted changes)
git worktree remove --force .

​

Verification

repo wt clean

# Output shows remaining worktrees automatically
# Verify this matches expectations

​

Alternative to Clean

# List all worktrees
repo wt list

# Remove each one individually
repo wt rm feature-a
repo wt rm feature-b

# Provides more control over what gets removed

​

See Also

• repo wt rm - Remove a specific worktree
• repo wt list - View all worktrees
• repo wt add - Create new worktrees
• Worktree Overview - Understanding worktrees