Tool

filedust

Autoremove for files: clean caches, build artifacts, editor junk.

Install Repo
Safety boundaries
  • Refuses to operate outside your $HOME (safety-first)
  • Default is interactive: one confirmation prompt at the end (default No)
  • Never touches dotfiles/configs unless you explicitly add rules
  • Dry-run shows what would be deleted without deleting anything
filedust logo

Quickstart

filedust                 # scan current dir (within $HOME)
filedust ~/src/project
filedust --dry-run ~/src/project
filedust -y ~/src/project
wget -O ~/.filedust.conf https://git.sysmd.uk/guardutils/filedust/raw/branch/main/.filedust.conf.example

Key features

Junk detection
Finds caches, build artifacts, temp/editor backup files.
Readable output
Rich table output + reclaimed space summary.
User rules
Load custom rules from ~/.filedust.conf.

How it works

Step 1
Scan
Traverse the target directory (must be within $HOME).
Step 2
Report
Print a table of junk items + potential reclaimed space.
Step 3
Confirm & delete
One prompt (or -y), delete files then directories.

What it finds

Out of the box, filedust targets common clutter like:

__pycache__/
.pytest_cache
.mypy_cache
.ruff_cache
build/
dist/
*~
*.swp
*.tmp
.DS_Store
Thumbs.db
TIP: Remember that filedust doesn't run outside of your $HOME.

Reference & examples

Everything for this tool on one page: options, behaviour notes, and copy-paste examples.

Rules & configuration

Get the example config

wget -O ~/.filedust.conf https://git.sysmd.uk/guardutils/filedust/raw/branch/main/.filedust.conf.example

Then edit ~/.filedust.conf to add or remove rules.

Practical tips

  • Start with --dry-run while tuning rules.
  • Add project-specific caches (e.g., tool outputs) as patterns.
  • Keep rules conservative; filedust is meant to target “obvious junk”.

Safety model

Home-directory enforcement

filedust refuses to operate outside your $HOME directory.

filedust /var/log
# Error: Refusing to operate outside the user's home directory.

One confirmation prompt

When not using --dry-run or -y, filedust asks once at the end (default No).

Cleanup confirmation
Do you want to clean this up? (y/N)

Usage & flags

Scan a directory

filedust
filedust ~/src/project

If no path is given, filedust scans the current directory.

Dry-run

filedust --dry-run ~/src/project

Shows what would be deleted but performs no deletions.

Non-interactive

Skip the confirmation prompt and delete immediately:

filedust -y ~/src/project

Version

filedust --version