Skip to content

Getting started

By the end of this page you will have Commit Check installed, rejecting a bad commit message on your machine, and wired into the two places it belongs.

It takes about five minutes and needs nothing but a Git repository.

On GitHub and want nothing to install?

Install the GitHub App: every push and pull request gets a Commit Check result, with no workflow file. The App guide covers what it checks. This page sets up the CLI and the hook, which work with any Git host.

1. Install

$ pip install commit-check

$ uv tool install commit-check

$ pipx install commit-check

Verify the install:

$ commit-check --version

The CLI is also available as cchk, which is the same program under a shorter name.

Supported Python versions

Commit Check supports Python 3.10 through 3.15, on Linux, macOS and Windows.

Running it as a pre-commit hook or a GitHub Action needs no installation step at all — both fetch it for you.

2. Watch it reject something

Commit Check works with no configuration at all. Make a deliberately bad commit in a scratch repository:

$ git init demo && cd demo
$ git commit --allow-empty -m "updated the parser"

Now check it:

$ commit-check --message

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

Four things are happening in that output, and each is deliberate:

Part What it gives you
CC001 A stable rule ID. It will mean the same thing in five years.
==> updated the parser The exact value that failed, not just "invalid message".
Suggest: What to do about it.
Docs: Why the rule exists, and how to configure or disable it.

3. Fix it

$ git commit --amend --allow-empty -m "fix(parser): handle empty input"
$ commit-check --message

It prints nothing and exits with code 0.

4. Check the branch too

$ git switch -c my-changes
$ commit-check --branch

CC201 branch check failed ==> my-changes
The branch should follow Conventional Branch. See https://conventionalbranch.org
Suggest: Use <type>/<description> with an allowed type, or add the branch to allow_branch_names in config
Docs: https://commit-check.com/rules/#cc201

Rename it to something structured and it passes:

$ git branch -m fix/empty-input
$ commit-check --branch

Checks are opt-in per run

commit-check --message never evaluates branch rules, and vice versa. Each check is selected by its own flag, so you can run exactly what a given hook or CI job needs. The rules reference lists which flag activates each rule.

5. Write down your policy

So far you have been running the defaults. Create a cchk.toml in the repository root — or in .github/ — to make the policy explicit:

cchk.toml
[commit]
conventional_commits = true
subject_imperative = true          # (1)!
subject_max_length = 72
allow_wip_commits = false          # (2)!

[branch]
conventional_branch = true
  1. Off by default. Turning it on rejects fixed a bug in favour of fix a bug.
  2. allow_* options describe what is permitted. Set to false to enforce.

Run it again and the new rules apply:

$ commit-check --message

Defaults are not "nothing"

Even with no config file, Conventional Commits, Conventional Branch, subject length limits of 5–80 characters, and author name/email patterns are enforced. Check the Default column in the rules reference before assuming a rule is off.

6. Make it automatic

Running the command by hand does not scale. Wire it into the two places it belongs:

  • Before the commit lands

    A pre-commit hook rejects the message as you write it, so nothing bad reaches the branch in the first place.

    Pre-commit hook

  • On every pull request

    A GitHub Action checks every commit in the PR and can comment on the PR with what needs fixing.

    GitHub Actions

Verifying the download

Every release is published with a signed build provenance attestation. To verify a release artifact came from this repository's build pipeline:

$ gh attestation verify commit_check-*.whl --repo commit-check/commit-check

Show that you use it

Put the badge in your README, so contributors know their commits will be checked before they open a pull request:

commit-check

[![commit-check](https://commit-check.com/badge.svg)](https://commit-check.com)

.. image:: https://commit-check.com/badge.svg
   :target: https://commit-check.com
   :alt: commit-check

Where to go next

  • Where to run it — pre-commit hook, GitHub Action, GitHub App: which to use, and how they combine.
  • Rules reference — every rule, what it does, why it matters, and how to configure it.
  • Configuration — every option, its type and default, plus the environment variable and CLI flag that override it.
  • Command-line recipes — checking a range, wiring up CI, reading the JSON output.
  • Troubleshooting — a check failing that you did not turn on, nothing running at all, and how to get a commit through when you have to.