fsweep 0.2.0

An advanced workspace cleanup tool for developers to reclaim disk space.

🧹 fsweep

fsweep is your friendly neighborhood workspace cleanup tool! It's designed to help developers mop up bulky development artifacts and sweep away disk-space-hogging junk with ease.

Whether it's a mountain of node_modules, a forgotten venv, or stale build caches, fsweep identifies the mess and helps you reclaim your disk space in seconds.

📦 Installation

fsweep is best managed with uv. If you don't have it yet, get it from astral.sh/uv.

uv tool install fsweep

⚡ Quickstart (30 seconds)

Safe first run (dry-run, current directory):

uv run fsweep

Machine-readable dry-run:

uv run fsweep --output json

Destructive run with hard-delete:

uv run fsweep --delete --yes-delete

Destructive run with recoverable trash mode:

uv run fsweep --delete --trash --yes-delete

The default scan path is your current working directory (.).

Options

Option	Shorthand	Description	Default
--path		The directory to scan for cleanup.	.
--force	-f	Skip final destructive confirmation prompt.	False
--dry-run / --delete	-d	Simulate cleanup (default) or enable destructive mode.	True
--trash		Move matched folders to ~/.fsweep_trash instead of hard delete.	False
--interactive		Select matched folders before execution.	False
--use-index / --no-index		Enable/disable scan size cache index.	True
--index-file		Path to scan index JSON file.	<scan_path>/.fsweep-index.json
--output		Output format: table or json.	table
--report		Write a markdown run report to a file.	unset
--config		Load a TOML config file.	unset
--target-folder		Add custom target folder names (repeatable).	[]
--exclude-pattern		Exclude glob patterns from scan (repeatable).	[]
--protected-path		Protect paths from scan/deletion (repeatable).	[]
--yes-delete		Required for destructive runs.	False
--best-effort		Continue and exit successfully even if deletes fail.	False
--max-delete-count		Max folders allowed in one destructive run.	50
--no-delete-limit		Override --max-delete-count.	False

⚙️ Config File (fsweep.toml)

fsweep loads config in this order (later wins):

1. ~/.config/fsweep/fsweep.toml
2. <scan_path>/fsweep.toml
3. --config /path/to/fsweep.toml
4. CLI flags

Example:

[fsweep]
target_folders = ["node_modules", "venv", "vendor_cache"]
exclude_patterns = ["**/.git/**", "**/keep/**"]
protected_paths = ["important", "../do-not-touch"]
max_delete_count = 75
no_delete_limit = false

protected_paths are resolved relative to the config file that defines them.

📤 JSON Output Contract

Use --output json for scripts/automation.

• schema_version: currently "1"
• summary: totals, counts, and effective action
• items[]: per-folder path, size, action, status, and optional error
• error responses also use JSON with error and exit_code

⚖️ Dry-run Parity Guarantee

fsweep now includes a dry-run parity test that guarantees the matched set in dry-run and destructive mode is identical for equivalent flags and path.

📈 Benchmark + Indexing

• --use-index caches directory size calculations in <scan_path>/.fsweep-index.json to speed repeated scans.
• Use --no-index to benchmark raw scan performance.
• Opt-in benchmark suite:

FSWEEP_BENCHMARK=1 ./.venv/bin/python -m pytest tests/test_fsweep/test_benchmark.py -q

🧹 What does it sweep?

fsweep knows exactly which corners to sweep. It currently targets:

• JavaScript/TypeScript: node_modules, .next, .nuxt, .svelte-kit, .astro, .turbo, .parcel-cache, .vite
• Python: venv, .venv, __pycache__, .pytest_cache, .tox, .nox, .mypy_cache, .ruff_cache, .ipynb_checkpoints
• Build/Test Artifacts: build, dist, out, coverage, htmlcov, .nyc_output, .cache
• JVM/.NET/Rust: .gradle, target, bin, obj
• Infrastructure-as-Code: .terraform, .terragrunt-cache

🚀 Key Features

• 🔍 Intelligent Scanning: Recursively hunts down common "junk" folders across your projects.
• 💰 Size Estimation: Calculates exactly how much space you'll recover before you commit.
• 📊 Rich Terminal UI: Presents findings in beautiful, easy-to-read tables thanks to Rich.
• 🛡️ Safety First: Includes a robust --dry-run mode and confirmation prompts to ensure your precious source code stays safe.
• 💨 Reach + Speed: Supports Python 3.10+ and keeps scan/deletion fast.

🧪 Development

Ready to help improve the fsweep? Here's how to keep the codebase as clean as your workspace.

git clone https://github.com/drew-simmons/fsweep.git
cd fsweep

uv sync

🛠️ Tech Stack

• Python 3.10+
• Typer: For a clean and intuitive CLI experience.
• Rich: For beautiful terminal output, tables, and progress indicators.
• uv: For lightning-fast dependency management.

Running Tests

uv run pytest

Exit Codes

• 0: successful run (or dry-run simulation complete)
• 1: safety check failure or invalid invocation
• 2: one or more deletions failed (unless --best-effort is set)

Linting & Formatting

We use Ruff to keep things tidy:

uv run ruff check .
uv run ruff format .
uv run rumdl fmt .

Type Checking

Keep the types in check with ty:

uv run ty check .

[!TIP] uv run prek -a runs all the above linting and formatting.

🔐 Safety Model

• Default mode is non-destructive (--dry-run).
• Destructive mode requires --delete --yes-delete.
• Optional --trash mode is destructive but recoverable.
• fsweep refuses to sweep / and your home directory root.
• Destructive runs are capped by --max-delete-count unless overridden.

📋 Release Checklist

Before tagging a release (v*), verify:

uv run pytest
uv run ruff check .
uv run ty check .
uv build
uv run --isolated --no-project --with dist/*.whl fsweep --help
uv run --isolated --no-project --with dist/*.whl python -m fsweep --help
uv run --isolated --no-project --with dist/*.tar.gz fsweep --help
uv run --isolated --no-project --with dist/*.tar.gz python -m fsweep --help