The typical pre-push hook recipe guesses which commits are being pushed:
npx --no -- commitlint --from=origin/main --to=HEADThis guess is wrong in many everyday scenarios:
origin/mainis stale or doesn't exist locally- the branch was forked from another branch, so already-pushed commits get re-linted (and can block the push even though those commits are already published)
- pushing multiple refs at once
- force pushes
- pushing tags or deleting branches
Git already tells the pre-push hook exactly what is being pushed — one line
per ref on stdin:
<local ref> <local sha> <remote ref> <remote sha>
commitlint-pre-push parses that input and derives the precise set of commits
for each ref update:
- branch update — commits between the remote sha and the local sha
- new branch — commits not present on any remote-tracking ref (so commits already pushed to any remote branch are never re-linted)
- force push — only the replacement commits
- branch deletion / tag push — nothing to lint, skipped
- multiple refs — each ref's commits, deduplicated
It then runs your project's own commitlint (your config, your version) on exactly those commits.
npm install -D commitlint-pre-pushAdd it to your pre-push hook. For example, with
husky:
# .husky/pre-push
commitlint-pre-pushOr with a plain .git/hooks/pre-push hook:
#!/bin/sh
npx --no -- commitlint-pre-pushThat's it — zero configuration. The remote, refs, and commit ranges all come from the data git passes to the hook.
Outside the hook, if no pre-push input arrives on stdin within a couple of
seconds, the tool falls back to a dry run instead of waiting
indefinitely. Non-interactive callers can skip the wait by redirecting stdin
from /dev/null:
npx --no -- commitlint-pre-push < /dev/nullRun it manually in a terminal to preview what a push of the current branch would lint:
npx --no -- commitlint-pre-push- Node.js >= 22
- @commitlint/cli >= 19 and a commitlint configuration in your project (see the setup guide)
MIT © 2026 Igor Danchenko