remove

Removes worktrees, tmux windows, and branches without merging (unless you keep the branches). Useful for abandoning work or cleaning up experimental branches. Supports removing multiple worktrees in a single command. Alias: rm

workmux remove [name]... [flags]

Arguments

• [name]...: One or more worktree names (the directory names). Defaults to current directory name if omitted.

Options

Flag	Description
--all	Remove all worktrees at once (except the main worktree). Prompts for confirmation unless --force is used. Safely skips worktrees with uncommitted changes or unmerged commits.
--gone	Remove worktrees whose upstream remote branch has been deleted (e.g., after a PR is merged on GitHub). Automatically runs git fetch --prune first.
--force, -f	Skip confirmation prompt and ignore uncommitted changes.
--keep-branch, -k	Remove only the worktree and tmux window while keeping the local branch.

Examples

# Remove the current worktree (run from within the worktree)
workmux remove

# Remove a specific worktree with confirmation if unmerged
workmux remove experiment

# Remove multiple worktrees at once
workmux rm feature-a feature-b feature-c

# Remove multiple worktrees with force (no confirmation)
workmux rm -f old-work stale-branch

# Use the alias
workmux rm old-work

# Remove worktree/window but keep the branch
workmux remove --keep-branch experiment

# Force remove without prompts
workmux rm -f experiment

# Remove worktrees whose remote branches were deleted (e.g., after PR merge)
workmux rm --gone

# Force remove all gone worktrees (no confirmation)
workmux rm --gone -f

# Remove all worktrees at once
workmux rm --all

Deferred filesystem cleanup

When removing a worktree from its own terminal target, filesystem cleanup runs in a detached worker after that target closes. Surviving background processes can still write into the renamed .workmux_trash_* directory. Rust cleanup continues deleting unrelated files and directories after an individual failure, using descriptor-relative operations without following symlink targets. Workmux retries DirectoryNotEmpty errors with backoff for a five-second retry window; an individual recursive deletion can take longer. It does not kill those processes.

Before renaming the worktree, Workmux saves a pending filesystem-cleanup record under $XDG_STATE_HOME/workmux/pending-cleanup/ (by default, ~/.local/state/workmux/pending-cleanup/). The record includes the original and quarantine paths and the captured directory’s device and inode. It is cleared only after filesystem deletion succeeds.

If deletion fails, the record remains and the worker writes the error and a bounded snapshot of remaining entries, along with the paths and errors from failed deletion operations, to workmux.log in the same state directory. Records also survive failures in intervening Git operations. They are diagnostic recovery records, not an automatic cleanup queue: inspect them and stop any remaining writers before manually recovering the exact quarantined directory. Do not replay branch deletion from a record, since Git cleanup may already have completed and the original branch or worktree path may have been reused.