commit-sentry

Zero-config git hooks for your team. Install once, and every teammate — on Windows, macOS, or Linux — gets the same pre-commit, commit-msg, and pre-push behavior. No git config steps, no CRLF surprises, no "works on my machine".

What you get

• Hooks auto-wired on npm install — no manual husky install, no manual git config core.hooksPath.
• prettier and lint-staged auto-installed — staged files are formatted on every commit, zero config needed.
• pre-commit: two phases on every commit:
  • Phase 1 — rm-console (opt-in): set CG_RM_CONSOLE=1 (inline or in .env) and every console.log / .warn / .debug / .info in staged .js/.jsx/.ts/.tsx files is stripped, re-formatted with prettier, and re-staged before the commit lands — so the clean version is what git actually stores. console.error is preserved.
  • Phase 2 — lint-staged: runs prettier (and ESLint after setup-eslint) on staged files.
• commit-msg: runs your build script and aborts if it fails. Skips silently when no build script exists. Detects .next/trace file locks on Windows and fails fast with a clear message.
• setup-eslint command: one command detects your framework (React+TS, React JS, TypeScript, plain JS) and scaffolds a full ESLint config + wires ESLint into lint-staged.
• Monorepo / subfolder support: works whether your git root is the same folder as your install or a parent directory (e.g. git root at /project, package installed in /project/frontend).
• Shareable prettier / eslint / lint-staged configs you can extend.
• Dynamic core.hooksPath: rename or relocate your project folder — still works.
• CRLF auto-heal: fixes hook files checked out with Windows line endings so bash: $'\r': command not found never happens.
• Safe postinstall: soft-fails in non-git environments (Docker builds, CI, tarball unpacks) — npm install never breaks.
• Easy bypass: HUSKY=0 or HUSKY_SKIP_BUILD=1 for one-off commits.

Install

npm install --save-dev commit-sentry

That's it. The following happen automatically on install:

| What | Result | |---|---| | Git hooks | Installed into .husky/, core.hooksPath set | | prettier | Installed as a dependency | | lint-staged | Installed as a dependency | | lint-staged.config.js | Created — runs prettier on staged files | | Non-git environments | Detected and skipped silently (CI, Docker) |

If you're adding this to a repo that already has files in .husky/, they're preserved. Run npx commit-sentry update to overwrite them with the package defaults.

Monorepo / subfolder install

Works out of the box. If your git root is a parent of your install directory:

/project/          ← git root
  frontend/        ← npm install commit-sentry runs here
    package.json
    node_modules/
    .husky/        ← hooks installed here automatically

core.hooksPath is set to frontend/.husky relative to the git root — no extra config needed.

ESLint setup (optional)

After installing, run one command to scaffold ESLint for your framework:

npx commit-sentry setup-eslint

This does everything in one shot:

1. Detects your project type (React + TypeScript, React JS, TypeScript, plain JS).
2. Installs the required ESLint plugins via npm install --save-dev.
3. Creates eslint.config.mjs with sensible defaults for your framework.
4. Updates lint-staged.config.js to run ESLint + prettier on every commit.

npx commit-sentry setup-eslint --force   # overwrite an existing ESLint config

Note: If you have a custom lint-staged.config.js, it won't be overwritten — you'll see a message telling you to add ESLint manually.

What gets installed per framework

| Framework | Detected by | ESLint plugins installed | |---|---|---| | React + TypeScript | react + typescript in deps | typescript-eslint, eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-jsx-a11y | | React (JavaScript) | react in deps | eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-jsx-a11y | | TypeScript (Node.js) | typescript in deps or tsconfig.json | typescript-eslint | | Plain JavaScript | fallback | @eslint/js, eslint-config-prettier | | Angular | @angular/core in deps | Guided to ng add @angular-eslint/schematics. Use --force to scaffold a TypeScript config instead. |

After setup-eslint — what runs on every commit

git commit
  → pre-commit hook
      Phase 1: rm-console (if CG_RM_CONSOLE=1 or CONSOLE_LOG_REMOVAL=true in .env)
        → strip console.log/.warn/.debug/.info from staged JS/TS files
        → prettier --write
        → git add (re-stage cleaned files)
      Phase 2: lint-staged
        → eslint --fix   (fixes auto-fixable issues, blocks on errors)
        → prettier --write  (formats code)
  → commit-msg hook
      → build check (npm run build)

CLI

npx commit-sentry setup                  # install hooks (same as postinstall)
npx commit-sentry update                 # force-overwrite hook files with package defaults
npx commit-sentry uninstall              # remove hooks and unset core.hooksPath
npx commit-sentry setup-eslint           # scaffold ESLint config for your framework
npx commit-sentry setup-eslint --force   # overwrite existing ESLint config
npx commit-sentry version                # print version
npx commit-sentry help                   # show help

Environment variables

| Variable | Effect | |---|---| | HUSKY=0 | Bypass all hooks for one command. | | HUSKY_SKIP_BUILD=1 | Skip the commit-time build for one commit. | | CG_BUILD_COMMAND | Override the build command (default: npm run build). | | CG_RM_CONSOLE=1 | Enable console stripping for this commit (inline). | | CONSOLE_LOG_REMOVAL=true | Enable console stripping permanently via .env file at repo root. | | CG_SKIP_RM_CONSOLE=1 | Disable console stripping even if CG_RM_CONSOLE or .env is set. |

# Strip console.logs for one commit:
CG_RM_CONSOLE=1 git commit -m "feat: dashboard"

# Strip console.logs on every commit (add to .env):
echo "CONSOLE_LOG_REMOVAL=true" >> .env

# Skip stripping for one commit (even if .env has the flag):
CG_SKIP_RM_CONSOLE=1 git commit -m "debug: keep logs"

# Skip the build this one time:
HUSKY_SKIP_BUILD=1 git commit -m "docs: typo"

# Use a custom build command:
CG_BUILD_COMMAND="npm run ci:check" git commit -m "fix: logic"

# Skip all hooks entirely:
HUSKY=0 git commit -m "wip"

The rm-console feature

Automatically strip console.log / .warn / .debug / .info from every staged .js/.jsx/.ts/.tsx file before it lands in the commit. console.error is always preserved.

Option A — inline flag (one commit):

CG_RM_CONSOLE=1 git commit -m "feat: new dashboard"

Option B — .env file (always-on):

# Add to .env at your repo root:
CONSOLE_LOG_REMOVAL=true

From that point on, every git commit automatically strips console statements — no inline flag needed.

What happens under the hood:

1. Finds every staged .js / .jsx / .ts / .tsx file.
2. Strips every console.log / console.warn / console.debug / console.info call (including multi-line calls with nested parens).
3. Re-formats those files with prettier.
4. Re-stages the cleaned files — so the stripped version is what git actually stores in the commit, not just what's left on disk.

Disable for one commit (even if .env has the flag):

CG_SKIP_RM_CONSOLE=1 git commit -m "debug: keeping console.logs"

Verify a commit was cleaned:

git show HEAD:src/yourfile.ts   # committed content — no console.log

Use the shareable configs manually

Prettier

In your package.json:

{
  "prettier": "commit-sentry/configs/prettier.config.js"
}

Lint-staged

// lint-staged.config.js — prettier only
module.exports = require("commit-sentry/configs/lint-staged-config");

// or with ESLint (after running npx commit-sentry setup-eslint):
module.exports = {
  "**/*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
  "**/*.{json,css,scss,md}": ["prettier --write"],
};

ESLint (flat config, ESLint 9+)

// eslint.config.mjs
import base from "commit-sentry/configs/eslint.config.mjs";

export default [
  ...base,
  {
    rules: {
      // your project-specific overrides
    },
  },
];

How it survives fresh clones

The postinstall script:

1. Locates the consumer's git repo root (soft-fails if not a git repo).
2. Creates .husky/ next to package.json if missing.
3. Copies hook templates in (won't overwrite existing hooks — that's what update is for).
4. Sets core.hooksPath relative to the repo root (handles monorepos and sub-folder projects correctly).
5. Normalizes CRLF → LF on every hook file (Windows safety).
6. Chmods hooks to 0755 on Unix.
7. Creates lint-staged.config.js if none exists.
8. Logs what it did. Every failure is a warning, never a hard error — npm install is sacred.

Uninstall

npx commit-sentry uninstall
npm uninstall commit-sentry

uninstall removes only the hook files this package created and unsets core.hooksPath. Any hooks you added yourself are left alone.

Troubleshooting

"The build fails with EPERM on .next/trace on Windows" Your dev server (npm run dev) is running in another terminal holding .next/ open. Stop it and re-commit, or bypass: HUSKY_SKIP_BUILD=1 git commit -m "...".

"Hooks don't run after I clone the repo" Run npx commit-sentry setup. This happens when npm install ran with --ignore-scripts or in a directory without a .git/ folder.

"bash: $'\r': command not found" Your hook files were checked out with CRLF endings. Run npx commit-sentry update to rewrite them to LF. Add .husky/** text eol=lf to .gitattributes to prevent recurrence.

"ESLint rules are not running on commit" Run npx commit-sentry setup-eslint. Without it, only prettier runs on commit — ESLint is opt-in.

"Prettier is not running on commit" Check that lint-staged.config.js exists in your project root. If missing, run npx commit-sentry setup to regenerate it.

License

MIT