commitlint-pre-push

Lint exactly the commits being pushed — an accurate commitlint wrapper for the pre-push git hook.

Why

The typical pre-push hook recipe guesses which commits are being pushed:

npx --no -- commitlint --from=origin/main --to=HEAD

This guess is wrong in many everyday scenarios:

• origin/main is 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.

Installation

npm install -D commitlint-pre-push

Usage

Add it to your pre-push hook. For example, with husky:

# .husky/pre-push
commitlint-pre-push

Or with a plain .git/hooks/pre-push hook:

#!/bin/sh
npx --no -- commitlint-pre-push

That'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/null

Dry run

Run it manually in a terminal to preview what a push of the current branch would lint:

npx --no -- commitlint-pre-push

Requirements

• Node.js >= 22
• @commitlint/cli >= 19 and a commitlint configuration in your project (see the setup guide)

License

MIT © Igor Danchenko