Commit Check¶

Overview¶

Commit Check (aka cchk) is an open-source tool that enforces commit metadata standards — including commit messages, branch naming, committer name/email, commit signoff, and more — helping teams maintain consistency and compliance.

As a lightweight alternative to GitHub Enterprise Metadata restrictions and Bitbucket’s paid plugin Yet Another Commit Checker, Commit Check integrates DevOps principles and Infrastructure as Code (IaC) practices for a modern workflow.

What’s New in v2.0.0¶

Version 2.0.0 is a major release featuring a new configuration format, a modernized architecture, and an improved user experience.

✨ Highlights

TOML Configuration — Replaces .commit-check.yml with cchk.toml or commit-check.toml for clearer, more consistent syntax.
Simplified CLI & Hooks — Legacy pre-commit hooks and options removed to deliver a cleaner, more streamlined interface.
New Validation Engine — Fully redesigned for greater flexibility, performance, and maintainability.

For the full list of updates and improvements, visit the What’s New page.

Installation¶

To install Commit Check, you can use pip:

pip install commit-check

Or install directly from the GitHub repository:

pip install git+https://github.com/commit-check/commit-check.git@main

Then, run commit-check --help or cchk --help (alias for commit-check) from the command line. For more information, see the docs.

Configuration¶

Commit Check can be configured in three ways (in order of priority):

Command-line arguments — Override settings for specific runs
Environment variables — Configure via CCHK_* environment variables
Configuration files — Use cchk.toml or commit-check.toml

Use Default Configuration¶

Commit Check uses a default configuration if you do not provide a cchk.toml or commit-check.toml file.
The default configuration is lenient — it only checks whether commit messages follow the Conventional Commits specification and branch names follow the Conventional Branch convention.

Use Custom Configuration File¶

To customize the behavior, create a configuration file named cchk.toml or commit-check.toml in your repository’s root directory or in the .github folder, e.g., cchk.toml or .github/cchk.toml.

Use CLI Arguments or Environment Variables¶

For one-off checks or CI/CD pipelines, you can configure via CLI arguments or environment variables:

# Using CLI arguments
commit-check --message --subject-imperative=true --subject-max-length=72

# Using environment variables
export CCHK_SUBJECT_IMPERATIVE=true
export CCHK_SUBJECT_MAX_LENGTH=72
commit-check --message

# In pre-commit hooks (.pre-commit-config.yaml)
repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.3.0
    hooks:
      - id: check-message
        args:
          - --subject-imperative=false
          - --subject-max-length=100

See the Configuration documentation for all available options.

Usage¶

For detailed usage instructions including pre-commit hooks, CLI commands, and STDIN examples, see the Usage Examples documentation.

Examples¶

Check Commit Message Failed

Commit rejected by Commit-Check.

  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)
   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \
 __\( C )/__  __\( H )/__  __\( E )/__  __\( C )/__  __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
   || E ||      || R ||      || R ||      || O ||      || R ||
 _.' '-' '._  _.' '-' '._  _.' '-' '._  _.' '-' '._  _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
 `-´     `-´  `-´     `-´  `-´     `-´  `-´     `-´  `-´     `-´

Commit rejected.

Type message check failed ==> test commit message check
It doesn't match regex: ^(chore|ci|docs|feat|fix|refactor|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)
The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
Suggest: Use <type>(<scope>): <description> with allowed types

Check Branch Naming Failed

Commit rejected by Commit-Check.

  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)
   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \
 __\( C )/__  __\( H )/__  __\( E )/__  __\( C )/__  __\( K )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
   || E ||      || R ||      || R ||      || O ||      || R ||
 _.' '-' '._  _.' '-' '._  _.' '-' '._  _.' '-' '._  _.' '-' '._
(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)(.-./`-´\.-.)
 `-´     `-´  `-´     `-´  `-´     `-´  `-´     `-´  `-´     `-´

Commit rejected.

Type branch check failed ==> test-branch
It doesn't match regex: ^(feature|bugfix|hotfix|release|chore|feat|fix)\/.+|(master)|(main)|(HEAD)|(PR-.+)
The branch should follow Conventional Branch. See https://conventional-branch.github.io/
Suggest: Use <type>/<description> with allowed types or ignore_authors in config branch section to bypass

More examples see example documentation.

Badging your repository¶

You can add a badge to your repository to show that you use commit-check!

Markdown

[![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd)](https://github.com/commit-check/commit-check)

reStructuredText

.. image:: https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd
    :target: https://github.com/commit-check/commit-check
    :alt: commit-check

Versioning¶

Versioning follows Semantic Versioning.

Have question or feedback?¶

Please post to issues for feedback, feature requests, or bug reports.

License¶

This project is released under the MIT License