You've just bootstrapped a new project. You have the code, the tests, the CI. Then a week later someone opens an issue asking for a license. Another asks why there's no CHANGELOG. Your package.json has been missing a description field since day one — you just never noticed.

This isn't a bug. It's a repo hygiene gap. And it's easy to miss when you're moving fast.

So I built repogap — a zero-dependency CLI that catches these gaps before they become problems.

What it checks

Run it in any repo:

$ repogap

  ✓ README.md
  ✗ LICENSE         missing
  ✓ .gitignore
  ! CHANGELOG       missing (recommended)

  package.json
    ✓ name          my-tool
    ✓ version       1.0.0
    ✗ description   missing or empty
    ✓ license       MIT
    ! repository    missing

repogap: drift detected — 2 errors, 2 warnings

File checks (auto-detected, all variants):

• README — accepts .md, .rst, .txt, bare
• LICENSE — accepts LICENCE, COPYING, .txt, .md
• .gitignore
• CHANGELOG — warn by default, accepts .md, .rst, HISTORY.md, etc.

Manifest field checks (auto-detects package.json or pyproject.toml):

• name, version, description, license — required
• repository — warn

Install (zero dependencies)

# Node — no install needed
npx repogap

# Python
pip install repogap
repogap

Both versions produce identical output. Drop either one into CI and it behaves the same way.

Flags

repogap --strict         # warnings become errors (exit 1)
repogap --no-changelog   # skip CHANGELOG check
repogap --no-fields      # skip manifest field checks
repogap --json           # machine-readable output
repogap ./packages/ui    # check a sub-package

Add to CI

- name: Check repo hygiene
  run: npx repogap

Or run it once before open-sourcing a private repo:

npx repogap

Design note: warnings vs errors

The distinction is intentional. Missing README, LICENSE, .gitignore, or a blank description are errors — they're either legally important (LICENSE), functionally broken (description shows up in npm search), or universally expected. A missing CHANGELOG and repository field are warnings — common gaps, but not blocking.

--strict collapses the distinction if you want zero tolerance.

Links

• npm: https://www.npmjs.com/package/repogap
• PyPI: https://pypi.org/project/repogap/
• GitHub (Node): https://github.com/jjdoor/repogap
• GitHub (Python): https://github.com/jjdoor/repogap-py

What's in your repo hygiene checklist? Is there a file or field you always forget to add? Curious what others have burned by.