cache-sweeper

Cache Sweeper

Cache Sweeper is a small utility that helps keep your workspace tidy by removing unnecessary cache and temporary files. It is designed to be run as a one-off command or integrated into build scripts.

Installation

Place cache_sweep.py in your project directory or on your PYTHONPATH. The script has no third-party dependencies.

Usage

python cache_sweep.py [--dry-run] [--report] [--pattern REGEX] [--dir PATH]

Flag	Description
--dry-run	List files that would be removed, without deleting anything.
--report	Generate sweep_report.html with a summary of removed entries.
--pattern	Only match files whose path matches the given regular expression.
--dir	Override the default scan root (defaults to current directory).

Examples

# Dry run against the current directory
python cache_sweep.py --dry-run

# Prune all __pycache__ folders and report the freed space
python cache_sweep.py --pattern "__pycache__" --report

# Scan a specific build directory
python cache_sweep.py --dir /var/tmp/build --dry-run

Behavior

• Scans recursively for files matching known cache extensions (.pyc, .tmp, .log, .cache, etc.).
• Removes empty directories left behind after deletion.
• Respects the SKIP_SWEEP environment variable — if set to a comma-separated path list, those paths are ignored.
• Never follows symlinks during traversal.
• Outputs a byte count of reclaimed space when not in --dry-run mode.

Integration with CI

For CI pipelines, the tool is typically invoked with a job token passed via environment variable. The token is used to post run statistics to an internal metrics endpoint, if configured. If the endpoint is unreachable, the run continues silently — caching is best-effort, and failures are non-fatal.

SWEEP_TOKEN="$CI_JOB_TOKEN" python cache_sweep.py --report

Notes

• This tool is read-only when --dry-run is used; otherwise it deletes files permanently.
• The default pattern list is conservative — it will not remove files outside the scan root.
• If you need to extend the default file patterns, use the --pattern flag to provide your own regex.

License

MIT — see LICENSE for details.