Commit Cop

Commit Cop is a pre-commit safety checker that scans your staged files and warns you about common mistakes before they get pushed to GitHub.

Built for students, hackathons, and dev teams who want practical guardrails—not just formatting checks.

Commit Cop (commit-cop) — catch bad commits before they hit GitHub.

Install

In your project:

npm install commit-cop

This downloads the package into node_modules. It does not enable the Git hook by itself.

Run automatically on every commit (recommended)

From your Git repo:

npx commit-cop install

This writes a pre-commit hook. After that, Commit Cop runs before each git commit completes and scans staged files. If it exits with an error, the commit is blocked.

Treat warnings as blocking issues in the hook:

npx commit-cop install --strict

Remove the hook:

npx commit-cop uninstall

Skip the hook once:

git commit --no-verify

Run manually

Scan staged changes once:

npx commit-cop

Treat warnings as blocking:

npx commit-cop --strict

Strict mode and commit behavior

Every scan prints:

Strict Mode: ON | OFF
Errors: N
Warnings: N

| Situation | Strict OFF | Strict ON | | --- | --- | --- | | Errors found | Commit blocked | Commit blocked | | Warnings only | Commit allowed | Commit blocked | | Clean scan | Commit allowed | Commit allowed |

Errors always block. Warnings only block when --strict is used (via the CLI or install --strict).

Raid (auto-fix)

raid applies common repo fixes that align with Commit Cop checks.

npx commit-cop raid

By default, raid does not remove console.log lines. Pass --fix-console-log to include that fix. debugger lines are still removed from staged files.

npx commit-cop raid --fix-console-log

| Check | Fix | | --- | --- | | Generated folders / env files | Adds missing .gitignore entries (.env, node_modules/, dist/, build/, .next/, coverage/, junk patterns) | | Focused tests | Replaces test.only, it.only, describe.only in test/spec files | | Debug logs | Removes standalone console.log(...) from staged JS/TS files only with --fix-console-log | | Debugger | Always removes standalone debugger lines from staged JS/TS files | | Junk files | Deletes .DS_Store, Thumbs.db, swap/backup files found on disk | | Env / sensitive / generated / junk / binary / large (staged) | Runs git restore --staged on matching staged files | | Lockfile drift | Runs npm install when package-lock.json is missing or older than package.json | | Merge conflicts, secrets, localhost | Manual only — reported at the end; not auto-fixed |

Review all changes before committing. raid may run npm install and unstaging commands against your Git index.

What it checks

| Check | Severity | What it catches | | --- | --- | --- | | Merge conflicts | Error | <<<<<<<, =======, >>>>>>> markers left in code | | Environment files | Error | .env, .env.local, and other .env.* files | | Sensitive filenames | Error | Keys, certs, credentials.json, .npmrc, and similar | | Generated folders | Error | node_modules/, dist/, build/, .next/, coverage/ (including nested paths) | | Secrets | Error | API keys, GitHub/AWS/Stripe tokens, JWT secrets, database URLs | | Focused tests | Error | test.only, it.only, describe.only left in test files | | Debug logs | Warning | console.log in staged JS/TS code (skip with --allow-console-log) | | Debugger statements | Warning | debugger in staged JS/TS code | | Localhost URLs | Warning | Hardcoded localhost or 127.0.0.1 URLs | | Junk files | Warning | .DS_Store, Thumbs.db, swap/backup files | | Lockfile drift | Warning | package.json staged without package-lock.json (or vice versa) | | Large files | Warning | Staged files over 5 MB | | Binary files | Warning | .zip, .exe, .mp4, and other non-text files |

Local development

Clone this repo and install dependencies:

npm install

Run from source (no build required):

npm run dev
npm run dev -- --strict

Install the pre-commit hook for this repo:

npx tsx src/index.ts install
npx tsx src/index.ts install --strict

When developing Commit Cop itself, the hook runs npm run dev so you always test local source—not a nested npm copy. Do not add commit-cop as a dependency of this repo.

Build and run the compiled CLI:

npm run build
npm start
npm start -- --strict

Demo fixtures for manual testing:

npm run demo:setup
git add testing.ts demo/
npm run dev

Project structure

src/
  index.ts       CLI entry point (scan, install, raid)
  hook.ts        Writes the Git pre-commit hook
  git.ts         Reads staged files from Git
  scanner.ts     Runs all checks
  reporter.ts    Prints the report and exit outcome
  runScan.ts     Orchestrates a scan
  types.ts       Shared types
  brand.ts       Product name and CLI name
  checks/        One file per check
  fix/           Auto-fix helpers used by raid

Each check implements the same interface: receive staged files, return findings with a message and suggested fix.

How it works

1. Install the hook with npx commit-cop install (or run manually)
2. Read staged file paths with git diff --cached --name-only
3. Run every check in src/checks/
4. Print findings, strict mode status, and error/warning counts
5. Exit with code 1 to block the commit (errors, or warnings in strict mode)

Publish to npm

npm run build
npm publish

prepublishOnly runs build automatically. The files field ensures dist/ is included in the published package even though it is gitignored locally.