Metadata-Version: 2.4
Name: bloatguard
Version: 0.1.0
Summary: Stop large files and junk (node_modules, build output, archives, .env, keys) from sneaking into a commit. A zero-dependency pre-commit guard.
Author: yyfjj
License: MIT
Project-URL: Homepage, https://github.com/jjdoor/bloatguard-py
Project-URL: Repository, https://github.com/jjdoor/bloatguard-py
Project-URL: Issues, https://github.com/jjdoor/bloatguard-py/issues
Keywords: git,pre-commit,hook,gitignore,large-files,lint,cli,devops,secrets
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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).

```bash
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

```bash
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

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

Or use it with the [pre-commit](https://pre-commit.com) framework / in CI:

```yaml
# .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`](https://www.npmjs.com/package/bloatguard)
(source: [bloatguard](https://github.com/jjdoor/bloatguard)).

## License

MIT
