resq-clean

Interactive, .gitignore-aware workspace cleaner for ResQ development. Provides a TUI that scans for build artifacts and gitignored files, lets you select what to remove, and reclaims disk space safely.

Overview

resq-clean walks the repository tree, applies .gitignore rules via the ignore crate (supporting negated patterns and nested .gitignore files), and presents every gitignored entry in an interactive list sorted by size. You can toggle individual items on or off before confirming deletion.

Cleanup Decision Tree

flowchart TD
    A[Launch resq-clean] --> B[Read .gitignore rules]
    B --> C[Walk repository tree]
    C --> D{For each path}

    D --> E{Is .git directory?}
    E -->|Yes| F[Skip]
    E -->|No| G{Matched by .gitignore?}

    G -->|No| F
    G -->|Yes| H[Calculate size]

    H --> I[Add to entries list]

    I --> J[Sort entries by size descending]
    J --> K[Display TUI]

    K --> L{User action}
    L -->|Space| M[Toggle item selection]
    M --> K
    L -->|Up/Down| N[Navigate list]
    N --> K
    L -->|Enter| O{--dry-run?}
    O -->|Yes| P[Exit without deleting]
    O -->|No| Q[Delete selected items]
    Q --> R[Re-scan workspace]
    R --> K
    L -->|q / Esc| S[Exit]

Installation

# From the workspace root
cargo build --release -p resq-clean

# Binary location
target/release/resq-clean

CLI Arguments

Usage Examples

Interactive TUI (default)

# Launch the cleanup TUI in the current directory
resq-clean

The TUI displays all gitignored files and directories sorted by size, with checkboxes. All items are selected by default.

Dry Run

# Preview mode -- nothing is deleted
resq-clean --dry-run

In dry-run mode, pressing Enter exits the TUI without performing any deletions, letting you inspect what would be removed.

Targeted Cleanup

# Run from a specific subdirectory
cd services/infrastructure-api && resq-clean

The scanner uses the current working directory as its root, so you can scope cleanup to a single service or library.

TUI Keybindings

What Gets Deleted

Anything matched by .gitignore rules, which typically includes:

Files matching negated gitignore entries (e.g., !dist/keep-this.json) are preserved automatically.

Environment Variables

No environment variables are required. The tool operates entirely on the local filesystem using the current working directory as its root.

Output Format

The TUI header displays the total size of all currently selected items (e.g., PENDING: 2.4 GB). Each entry in the list shows:

[x] <icon> <relative-path>                      <size>

• [x] / [ ] -- selection checkbox
• Icon -- folder or file indicator
• Relative path -- path relative to the scan root
• Size -- human-readable size (B, KB, MB, GB)

After deletion, the workspace is re-scanned and the list refreshes to reflect the current state.

Safety Notes

• Dry-run first: Always use --dry-run on the first pass to review what will be removed.
• Gitignore-only: Only files and directories matched by .gitignore rules are candidates for deletion. Tracked files are never touched.
• Negated patterns respected: Entries matching negated patterns (e.g., !important.log) are excluded from the scan.
• No .git deletion: The .git directory and its contents are unconditionally skipped.
• Interactive confirmation: Nothing is deleted until you press Enter in the TUI. You can deselect individual items with Space before confirming.
• Re-scan after deletion: After deleting, the tool re-scans to show the updated state, so you can verify the results.
• Directories removed recursively: Selected directories are removed with remove_dir_all. Ensure you have deselected anything you want to keep.

When to Use

• Before committing, to ensure no build artifacts slip through
• After switching branches, to avoid stale build caches
• Periodic deep clean when disk space is low

For ecosystem-specific cleanup without the TUI:

cargo clean                                              # Rust only
rm -rf services/coordination-hce/node_modules            # Node only
find . -type d -name __pycache__ -exec rm -rf {} +       # Python only

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.