bloatguard

Stop large files and junk from sneaking into a commit. bloatguard scans what you're about to commit and blocks the stuff that shouldn't be in version control — a 200 MB binary, a stray node_modules/, build output, a .env full of secrets, a private key. Run it by hand or wire it into a pre-commit hook. Zero dependencies.

npx bloatguard                  # scan staged files
npx bloatguard install          # add it as a .git/hooks/pre-commit guard

The problem

Committing a file you didn't mean to is cheap to do and expensive to undo. A giant binary or an accidental node_modules/ bloats the repo permanently — removing it later means rewriting history (git filter-repo, BFG) and a force-push that ruins everyone's day. A committed .env or *.pem is worse: once it's pushed, the secret is burned.

.gitignore helps, but only for files you remembered to list, and a stray git add -f or a pre-existing tracked file walks right past it. bloatguard is the backstop: it looks at what's actually staged and says "are you sure?"

What it flags

1. Big files — anything over --max-size (default 5 MB), whatever it is.

2. Junk patterns — a curated set of things that almost never belong in git:

   | Category | Examples | |----------|----------| | deps | node_modules/, bower_components/, .venv/ | | build | dist/, build/, target/, coverage/ | | archives | *.zip, *.tar.gz, *.rar, *.7z | | databases | *.sqlite, *.db | | binaries | *.exe, *.dll, *.so, *.dylib, *.class | | secrets | .env (not .env.example), *.pem, *.key, *.p12 | | OS / editor | .DS_Store, Thumbs.db, *.swp, *~ |

   Run bloatguard rules to see the full list.

Usage

bloatguard                       # = bloatguard check — scan the staged set
bloatguard scan                  # scan the whole working tree (honors .gitignore)
bloatguard scan src test         # scan only certain paths
bloatguard --max-size 50M        # raise the size limit
bloatguard --allow "assets/*.zip"  # whitelist a glob (repeatable)
bloatguard --json                # machine-readable
bloatguard rules                 # list the built-in patterns

As a pre-commit hook

bloatguard install     # writes .git/hooks/pre-commit (refuses to clobber an existing hook)
bloatguard uninstall

Once installed, a commit that stages anything flagged is blocked:

$ git commit -m "wip"
bloatguard 2 item(s) should not be committed (14 staged file(s) scanned)

  ✗ node_modules/ (1240 files, 88.4 MB)  — dependency directory — reinstall instead of committing
  ✗ .env (412 B)  — .env file — may contain secrets

Fix: add the pattern to .gitignore then git rm --cached <file>, or keep it on purpose with --allow <glob> / --max-size <size>

Or drop it into CI:

- run: npx bloatguard scan   # exit 1 fails the job

Exit codes

| Code | Meaning | |------|---------| | 0 | clean — nothing to scrub | | 1 | something staged shouldn't be committed (blocks the commit as a hook) | | 2 | not a git repository, or bad arguments |

Notes

• It only ever reads — bloatguard never modifies, stages, or deletes anything. It reports and sets an exit code; the fix is yours to make.
• A whole junk directory collapses into one line with a file count and total size, so staging an un-ignored node_modules/ doesn't flood your terminal.
• Output is deterministic (entries are sorted), so the Node and Python ports produce identical results.

Also available for Python

Same checks, same flags: pip install bloatguard (source: bloatguard-py).

License

MIT