bloatguard 0.1.0

Stop large files and junk (node_modules, build output, archives, .env, keys) from sneaking into a commit. A zero-dependency pre-commit guard.

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 (pure standard library).

pip install bloatguard

bloatguard                  # scan staged files
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

You can also run it as a module: python -m bloatguard.

As a pre-commit hook

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

Or use it with the pre-commit framework / in CI:

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: bloatguard
      name: bloatguard
      entry: bloatguard check
      language: system
      pass_filenames: false

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>

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 Python and Node ports produce identical results.

Also available for Node

Same checks, same flags: npx bloatguard (source: bloatguard).

License

MIT