Skip to content

Command-line recipes

Ways to invoke the checks directly. For wiring them into a workflow, see Integrations instead — that covers the setup this page assumes you already have.

Every option, and the environment variable and TOML key that set it, is listed in Configuration.

Checking a commit message

The message can come from the repository, a file, or standard input.

Validates HEAD's message. This is what the commit-msg hook runs.

$ commit-check -m

$ commit-check -m commit_message.txt

Useful in scripts and for trying a message before committing it.

$ echo "feat(auth): add OAuth2 login" | commit-check -m

Trying a message before you write it

$ echo "updated the parser" | commit-check -m
CC001 message check failed ==> updated the parser
The commit message should follow Conventional Commits.
Suggest: Use <type>(<scope>): <description>, where <type> is one of: feat, fix, ...
Docs: https://commit-check.com/rules/#cc001

Fix it and it goes quiet:

$ echo "fix(parser): handle empty input" | commit-check -m

Multi-line messages

A body and trailers survive a heredoc, so you can test the whole thing:

$ cat > /tmp/msg.txt << 'EOF'
fix(auth): resolve login timeout

Users were timing out during login. Raises the session timeout and
reports the failure instead of hanging.

Fixes #123
EOF
$ commit-check -m /tmp/msg.txt

Checking the branch

$ commit-check --branch

Runs CC201, and CC202 if require_rebase_target is set. master, main, HEAD and PR-* are always accepted; everything else needs a <type>/<description> shape:

fix/empty-config-crash
feature/role-caching
release/v1.2.0

Checking the committer

$ commit-check --author-name --author-email

Either flag works alone. CC101 and CC102 describe what the built-in patterns accept and how to tighten them.

Blocking force pushes

$ commit-check --no-force-push

Compares the current branch against its upstream and fails if pushing would require a force. Better as a pre-push hook, which sees the actual refs being pushed:

.pre-commit-config.yaml
repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.13.0
    hooks:
      - id: check-no-force-push
        stages: [pre-push]

Piping git push into it does not prevent anything

git push | commit-check --no-force-push reads too late — the push has already started — and git push output does not carry the ref lines Git hands to a pre-push hook. Install the hook instead.

Pointing at a different config

$ commit-check -m --config /path/to/cchk.toml

Useful for testing a policy change before committing it, or for a monorepo where one directory follows different rules. See Configuration for where the file is looked up by default and how CLI, environment and file settings override each other.

Output for scripts and CI

Machine-readable, one object per check, including rule_id and docs_url.

$ commit-check -m --format json

One line per failure. Implies --no-banner.

$ commit-check -m --compact
[FAIL] CC003 subject_imperative: docs: revamped the profile

Plain text without the ASCII art, which is noise in a CI log.

$ commit-check -m --no-banner

Reports problems but always exits 0. For adopting the policy on a repository whose history is not clean yet.

$ commit-check -m --dry-run

Checking a range of commits

Nothing built in, but the exit code makes it a one-liner:

check-recent.sh
#!/usr/bin/env bash
# Check the last N commit messages; exits non-zero if any fail.

# Resolved before the loop rather than inside it: an unreadable range or a
# directory that is not a repository would otherwise expand to nothing, and
# a loop that never runs would report success.
shas=$(git rev-list -n "${1:-10}" HEAD) || exit 1

status=0
for sha in $shas; do
  if ! git log -1 --format=%B "$sha" | commit-check -m --compact; then
    echo "  ↑ $sha"
    status=1
  fi
done
exit $status

Reading the JSON

$ commit-check -m --format json | jq -r '.checks[] | select(.status == "fail") | .rule_id'
CC001

Each failed check carries the rule ID, the offending value, the suggestion and a link to its documentation — the same information the text output prints, in a form other tools can consume.