From the root directory of the repository, do the following to steps
+Install docs’ dependencies
+pip install nox
+Build the docs
+nox -s docs
+Browse the files in /_build/html with your internet browser to see the rendered +output.
+All notable changes to this project will be documented in this file.
+Full changelog available at GitHub releases.
+Attention
+This major release introduces significant architectural changes and breaking updates to commit-check. Please review carefully before upgrading.
+TOML Configuration — Replaces the old .commit-check.yml with cchk.toml or commit-check.toml for clearer syntax.
Simplified CLI & Hooks — Legacy pre-commit hooks and command-line options have been removed for a cleaner, more consistent interface.
New Validation Engine — The validation system has been completely redesigned around a new ValidationEngine to improve maintainability and flexibility.
Configuration Format:
+.commit-check.yml has been replaced with cchk.toml or commit-check.toml.
All YAML configurations must be migrated to TOML from this version onward.
See the Migration Guide for step-by-step instructions.
Removed Pre-commit Hooks and CLI Options:
+Several legacy hooks and command-line flags have been removed in favor of a simplified interface.
Removed hooks: check-commit-signoff, check-merge-base, check-imperative.
Removed CLI options: --signoff, --merge-base, --imperative.
Module Removal:
+The following legacy modules have been removed: author.py, branch.py, commit.py, error.py.
Architecture Redesign:
+The validation system has been completely restructured around the new ValidationEngine, breaking compatibility with any code or integrations relying on the old module structure.
See PR #280
+Last release before the big v2.0 changes.
+Initial release of commit-check.
+ + + + + + + + + + + + + + + + +usage: commit-check [-h] [-v] [-c CONFIG] [-m [MESSAGE]] [-b] [-n] [-e] [-d]
+Check commit message, branch name, author name, email, and more.
+options:
+show this help message and exit
+show program’s version number and exit
+path to config file (cchk.toml or commit-check.toml). +If not specified, searches for cchk.toml in current +directory
+validate commit message. Optionally specify file path, +otherwise reads from stdin if available
+check current git branch name
+check git author name
+check git author email
+perform a dry run without failing (always returns 0)
+commit-check configuration files support the TOML format. See cchk.toml for an example configuration.
Tip
+Default Behavior
+When no configuration file exists, commit-check uses sensible defaults with minimal restrictions.
Only conventional commits format, subject capitalization, and imperative mood are enforced by default.
No length limits, author restrictions, or rebase requirements are applied.
commit-check can be configured via a cchk.toml or commit-check.toml file.
The file should be placed in the root of your repository.
+[commit]
+# https://www.conventionalcommits.org
+conventional_commits = true
+subject_capitalized = false
+subject_imperative = false
+# subject_max_length = 50 # Optional - no limit by default
+# subject_min_length = 5 # Optional - no limit by default
+allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
+allow_merge_commits = true
+allow_revert_commits = true
+allow_empty_commits = false
+allow_fixup_commits = true
+allow_wip_commits = false
+require_body = false
+# ignore_authors = [] # Optional - no authors ignored by default
+require_signed_off_by = false
+# required_signoff_name = "Your Name" # Optional
+# required_signoff_email = "your.email@example.com" # Optional
+
+[branch]
+# https://conventional-branch.github.io/
+conventional_branch = true
+allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
+# allow_branch_names = [] # Optional - additional standalone branch names (e.g., ["develop", "staging"])
+# require_rebase_target = "main" # Optional - no rebase requirement by default
+# ignore_authors = [] # Optional - no authors ignored by default
+Section |
+Option |
+Type |
+Default |
+Description |
+
|---|---|---|---|---|
commit |
+conventional_commits |
+bool |
+true |
+Enforce Conventional Commits specification. |
+
commit |
+subject_capitalized |
+bool |
+true |
+Subject must start with a capital letter. |
+
commit |
+subject_imperative |
+bool |
+true |
+Subject must be in imperative mood. Forms of verbs can be found at imperatives.py |
+
commit |
+subject_max_length |
+int |
+None (no limit) |
+Maximum length of the subject line. |
+
commit |
+subject_min_length |
+int |
+None (no limit) |
+Minimum length of the subject line. |
+
commit |
+allow_commit_types |
+list[str] |
+[“feat”, “fix”, “docs”, “style”, “refactor”, “test”, “chore”] |
+Allowed commit types when conventional_commits is true. |
+
commit |
+allow_merge_commits |
+bool |
+true |
+Allow merge commits. |
+
commit |
+allow_revert_commits |
+bool |
+true |
+Allow revert commits. |
+
commit |
+allow_empty_commits |
+bool |
+false |
+Allow empty commits. |
+
commit |
+allow_fixup_commits |
+bool |
+true |
+Allow fixup commits (e.g., “fixup! <commit message>”). |
+
commit |
+allow_wip_commits |
+bool |
+false |
+Allow work-in-progress commits (e.g., “WIP: <commit message>”). |
+
commit |
+require_body |
+bool |
+false |
+Require a body in the commit message. |
+
commit |
+ignore_authors |
+list[str] |
+[] (none ignored) |
+List of authors to ignore (i.e., always allow). |
+
commit |
+require_signed_off_by |
+bool |
+false |
+Require “Signed-off-by” line in the commit message footer. |
+
branch |
+conventional_branch |
+bool |
+true |
+Enforce Conventional Branch specification. |
+
branch |
+allow_branch_types |
+list[str] |
+[“feature”, “bugfix”, “hotfix”, “release”, “chore”, “feat”, “fix”] |
+Allowed branch types when conventional_branch is true. |
+
branch |
+allow_branch_names |
+list[str] |
+[] (empty list) |
+Additional standalone branch names allowed when conventional_branch is true (e.g., [“develop”, “staging”]). By default, master, main, HEAD, and PR-* are always allowed. |
+
branch |
+require_rebase_target |
+str |
+None (no requirement) |
+Target branch for rebase requirement. If not set, no rebase validation is performed. |
+
branch |
+ignore_authors |
+list[str] |
+[] (none ignored) |
+List of authors to ignore (i.e., always allow). |
+
This guide demonstrates how to use commit-check to validate commit messages, branch names, and author information.
+There are several ways to use commit-check: as a pre-commit hook, via STDIN, or directly with files.
+Please see commit-check/commit-check-action
+Install pre-commit:
Tip
+Make sure pre-commit is installed.
pip install pre-commit
+Create .pre-commit-config.yaml:
- repo: https://github.com/commit-check/commit-check
+ rev: the tag or revision
+ hooks:
+ - id: check-message
+ stages: [commit-msg]
+ - id: check-branch
+ - id: check-author-name
+ - id: check-author-email
+Install the hooks:
pre-commit install --hook-type pre-commit --hook-type commit-msg
+Test the integration:
# This will trigger validation automatically
+git commit -m "feat: add new user authentication system"
+✅ Successful Validation:
+$ git commit -m "feat: add user authentication system"
+
+check commit message.....................................................Passed
+check committer name.....................................................Passed
+check committer email....................................................Passed
+[main abc1234] feat: add user authentication system
+❌ Failed Validation:
+$ git commit -m "bad commit message"
+
+check commit message.....................................................Failed
+- hook id: check-message
+- exit code: 1
+
+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 ==> bad commit message
+It doesn't match regex: ^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .+
+The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
+Suggest: Use <type>(<scope>): <description> with allowed types
+Commit-check provides several command-line options for different validation scenarios. via options or STDIN
+Tip
+Validate commit messages by piping them through STDIN. This is useful for testing or scripting.
+Available Commands see commit-check –help
+# Validate message from STDIN
+echo "feat: new feature" | commit-check -m
+
+# Validate message from file
+commit-check -m commit_message.txt
+
+# Validate current git commit message (from git log)
+commit-check -m
+Reading from file:
+# Create a commit message file
+cat > commit_message.txt << EOF
+fix(auth): resolve login timeout issue
+
+Users were experiencing timeouts during login.
+Increased session timeout and improved error handling.
+
+Fixes #123
+EOF
+
+# Validate from file
+commit-check -m commit_message.txt
+
+# Or pipe file content
+cat commit_message.txt | commit-check -m
+# Check current branch name
+commit-check --branch
+
+# Example valid branch names:
+# - feature/user-auth
+# - fix/login-bug
+# - hotfix/security-patch
+# - release/v1.2.0
+# Check author name
+commit-check --author-name
+
+# Check author email
+commit-check --author-email
+
+# Check both author name and email
+commit-check --author-name --author-email
+# Use custom configuration file
+echo "feat: test" | commit-check --config my-config.toml -m
+
+# Use configuration from different directory
+commit-check --config /path/to/config/cchk.toml -m
+# Basic feature
+echo "feat: add user registration" | commit-check -m
+
+# Feature with scope
+echo "feat(auth): implement OAuth2 login" | commit-check -m
+
+# Bug fix
+echo "fix: resolve memory leak in parser" | commit-check -m
+
+# Documentation update
+echo "docs: add installation guide" | commit-check -m
+
+# Breaking change
+echo "feat!: redesign API endpoints" | commit-check -m
+
+# Merge commit (automatically allowed)
+echo "Merge pull request #123 from feature/new-api" | commit-check -m
+# No type prefix
+echo "added new feature" | commit-check -m
+
+# Capitalized (if configured to disallow)
+echo "feat: Add new feature" | commit-check -m
+
+# Too short
+echo "fix" | commit-check -m
+
+# Non-imperative mood
+echo "feat: added login functionality" | commit-check -m
+
+# Unknown type
+echo "unknown: some changes" | commit-check -m
+Commit Message Validation Failure:
+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
+Branch Name Validation Failure:
+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
+Commit Signature Validation Failure:
+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 require_signed_off_by check failed ==> fix: add missing file
+It doesn't match regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
+Signed-off-by not found in latest commit
+Suggest: git commit --amend --signoff or use --signoff on commit
+Imperative Mood Validation Failure:
+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 imperative check failed ==> fix: added missing file
+It doesn't match regex:
+Commit message should use imperative mood (e.g., 'Add feature' not 'Added feature')
+Suggest: Use imperative mood in the subject line
+You can use commit-check in CI/CD pipelines:
+# In your CI script
+git log --format="%s" -n 1 | commit-check -m
+
+# or just
+commit-check -m
+Use commit-check in scripts to validate commit messages programmatically:
+#!/bin/bash
+# validate-commits.sh
+
+# Get all commit messages from last 10 commits
+for i in {0..9}; do
+ msg=$(git log --format="%s" -n 1 --skip=$i)
+ if [ -n "$msg" ]; then
+ echo "Validating: $msg"
+ echo "$msg" | commit-check -m || exit 1
+ fi
+done
+
+echo "All commits are valid!"
+For more configuration options, see the Configuration Documentation.
+ + + + + + + + + + + + + + + + +
|
+
|
+
| + |
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.
+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.
+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.
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.
To customize the behavior, create a configuration file named cchk.toml or commit-check.toml in your repository’s root directory, e.g., cchk.toml
For detailed usage instructions including pre-commit hooks, CLI commands, and STDIN examples, see the Usage Examples documentation.
+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.
+You can add a badge to your repository to show that you use commit-check!
+
+
+Markdown
+[](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 follows Semantic Versioning.
+Please post to issues for feedback, feature requests, or bug reports.
+This project is released under the MIT License
+This guide helps you migrate from commit-check v1.x (YAML configuration) to v2.0+ (TOML configuration).
+Version 2.0 introduces significant changes to commit-check:
+Configuration format: .commit-check.yml → cchk.toml or commit-check.toml
Simplified architecture: New validation engine with cleaner design
Enhanced functionality: Better error messages and more flexible configuration options
Backup your existing configuration:
+cp .commit-check.yml .commit-check.yml.backup
+Create new TOML configuration:
+touch cchk.toml # or commit-check.toml
+Convert YAML to TOML format (see examples below)
Test the new configuration:
+commit-check --help
+commit-check --message --branch --author-name --author-email --dry-run
+Remove old YAML file:
+rm .commit-check.yml.backup # after confirming everything works
+The configuration structure has changed from YAML to TOML format
+Old YAML format (.commit-check.yml):
checks:
+- check: message
+ regex: '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)'
+ error: "The commit message should be structured as follows:\n\n
+ <type>[optional scope]: <description>\n
+ [optional body]\n
+ [optional footer(s)]\n\n
+ More details please refer to https://www.conventionalcommits.org"
+ suggest: please check your commit message whether matches above regex
+
+- check: branch
+ regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)
+ error: "Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/"
+ suggest: run command `git checkout -b type/branch_name`
+
+- check: author_name
+ regex: ^[A-Za-zÀ-ÖØ-öø-ÿ\u0100-\u017F\u0180-\u024F ,.\'-]+$|.*(\[bot])
+ error: The committer name seems invalid
+ suggest: run command `git config user.name "Your Name"`
+
+- check: author_email
+ regex: ^.+@.+$
+ error: The committer email seems invalid
+ suggest: run command `git config user.email yourname@example.com`
+
+- check: commit_signoff
+ regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
+ error: Signed-off-by not found in latest commit
+ suggest: run command `git commit -m "conventional commit message" --signoff`
+
+- check: merge_base
+ regex: main # it can be master, develop, devel etc based on your project.
+ error: Current branch is not rebased onto target branch
+ suggest: Please ensure your branch is rebased with the target branch
+
+- check: imperative
+ regex: '' # Not used for imperative mood check
+ error: 'Commit message should use imperative mood (e.g., "Add feature" not "Added feature")'
+ suggest: 'Use imperative mood in commit message like "Add", "Fix", "Update", "Remove"'
+New TOML format (cchk.toml or commit-check.toml):
[commit]
+# https://www.conventionalcommits.org
+conventional_commits = true
+subject_capitalized = false
+subject_imperative = true
+subject_max_length = 80
+subject_min_length = 5
+allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "ci"]
+allow_merge_commits = true
+allow_revert_commits = true
+allow_empty_commits = false
+allow_fixup_commits = true
+allow_wip_commits = false
+require_body = false
+require_signed_off_by = false
+ignore_authors = ["dependabot[bot]", "copilot[bot]"]
+
+[branch]
+# https://conventional-branch.github.io/
+conventional_branch = true
+allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
+require_rebase_target = "main"
+The command-line interface has been simplified:
+Old CLI (v1.x):
+commit-check --config .commit-check.yml
+New CLI (v2.0+):
+commit-check --config cchk.toml # or commit-check.toml
+# Or use defaults (no config file needed)
+commit-check --message --branch
+Issue: “Configuration file not found”
+Solution: Ensure your file is named cchk.toml or commit-check.toml and placed in the repository root.
Issue: “Invalid TOML syntax”
+Solution: Use a TOML validator or check the syntax. Common issues include:
+Missing quotes around strings
Incorrect boolean values (use true/false, not True/False)
Invalid array syntax
Issue: “Validation rules not working as expected”
+Solution: Check the Configuration Documentation for the correct option names and formats.
+After migration, test your configuration:
+# Test commit message validation
+echo "feat: test commit message" | commit-check --message
+
+# Test branch validation
+commit-check --branch
+
+# Test with dry-run flag
+commit-check --message --branch --author-name --author-email --dry-run
+Documentation: Check the Configuration Guide
Issues: Report problems on GitHub Issues
In some cases, Commit Check may fail due to an invalid author_name, as shown below:
check committer name.....................................................Failed
+- hook id: check-author-name
+- exit code: 1
+
+Commit rejected by Commit-Check.
+
+Type author_name check failed => 12
+It doesn't match regex: ^[A-Za-zÀ-ÖØ-öø-ÿ\u0100-\u017F\u0180-\u024F ,.\'-]+$|.*(\[bot])
+The committer name seems invalid
+Suggest: run command `git config user.name "Your Name"`
+To fix it, you can either update your Git config or temporarily skip the check using one of the following methods.
+Use the --no-verify flag to skip the pre-commit hook:
# Amend the commit without running hooks
+git commit --amend --author="Xianpeng Shen <xianpeng.shen@gmail.com>" --no-edit --no-verify
+Alternatively, use the SKIP=your-hook-name environment variable, like below:
# Set the correct Git author name
+git config user.name "Xianpeng Shen"
+
+# Force amend while skipping the specified hook
+SKIP=check-author-name git commit --amend --author="Xianpeng Shen <xianpeng.shen@gmail.com>" --no-edit
+This document highlights the major changes and improvements in each version of commit-check.
+Version 2.0.0 represents a complete architectural overhaul of commit-check, introducing significant improvements in configuration, usability, and maintainability.
+The most significant change in v2.0.0 is the transition from YAML to TOML configuration format, along with a complete redesign of the validation engine using SOLID principles.
+Key Benefits:
+Simplified Configuration: More intuitive TOML syntax
Better Defaults: Sensible out-of-the-box behavior
Enhanced Validation: Built-in support for Conventional Commits and Conventional Branches
Improved Architecture: Modular, maintainable codebase
Better Documentation: Comprehensive guides and examples
Configuration Guide: Updated Configuration Documentation with comprehensive examples
Migration Support: Complete Migration Guide for upgrading from v1.x to v2.0+
The configuration format has changed from YAML to TOML, providing better readability and easier maintenance.
+Format Comparison:
+Feature |
+YAML (v1.x) |
+TOML (v2.0+) |
+
|---|---|---|
Syntax |
+Complex nested structure |
+Simple key-value pairs |
+
Validation |
+Custom regex patterns |
+Built-in conventional standards |
+
Configuration |
+
|
+
|
+
Maintainability |
+Manual regex maintenance |
+Standardized patterns |
+
Below are side-by-side comparisons showing how common configurations translate from v1.x to v2.0+.
+Transform complex regex patterns into simple, standardized configuration.
+Before (YAML v1.x):
+checks:
+ - check: message
+ regex: '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)|(Merge).*|(fixup!.*)'
+ error: "The commit message should be structured as follows:\n\n
+ <type>[optional scope]: <description>\n
+ [optional body]\n
+ [optional footer(s)]\n\n
+ More details please refer to https://www.conventionalcommits.org"
+ suggest: please check your commit message whether matches above regex
+After (TOML v2.0+):
+[commit]
+conventional_commits = true
+allow_commit_types = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "style", "test"]
+Benefits: No more complex regex patterns, built-in Conventional Commits support, clearer configuration.
+Standardize branch naming with conventional patterns.
+Before (YAML v1.x):
+checks:
+ - check: branch
+ regex: ^(bugfix|feature|release|hotfix|task|chore)\/.+|(master)|(main)|(HEAD)|(PR-.+)
+ error: "Branches must begin with these types: bugfix/ feature/ release/ hotfix/ task/ chore/"
+ suggest: run command `git checkout -b type/branch_name`
+After (TOML v2.0+):
+[branch]
+conventional_branch = true
+allow_branch_types = ["bugfix", "feature", "release", "hotfix", "task", "chore"]
+Benefits: Built-in Conventional Branch support, automatic handling of special branches (main, master, HEAD, PR-*).
+Flexible author validation with allow/ignore lists.
+Before (YAML v1.x):
+checks:
+ - check: author_name
+ regex: ^[A-Za-zÀ-ÖØ-öø-ÿ\u0100-\u017F\u0180-\u024F ,.\'-]+$|.*(\[bot])
+ error: The committer name seems invalid
+ suggest: run command `git config user.name "Your Name"`
+After (TOML v2.0+):
+[commit]
+# Built-in validation with sensible defaults for author name/email
+# Optional: ignore specific authors (e.g., bots)
+ignore_authors = ["dependabot[bot]", "renovate[bot]"]
+Benefits: Built-in validation patterns, flexible ignore lists, automatic bot detection.
+Simple boolean flag for DCO compliance.
+Before (YAML v1.x):
+checks:
+ - check: commit_signoff
+ regex: Signed-off-by:.*[A-Za-z0-9]\s+<.+@.+>
+ error: Signed-off-by not found in latest commit
+ suggest: run command `git commit -m "conventional commit message" --signoff`
+After (TOML v2.0+):
+[commit]
+require_signed_off_by = true
+Benefits: Simple boolean configuration, built-in DCO validation, clear error messages.
+SOLID Principles: Maintainable, extensible design
Specialized Validators: Dedicated classes for each validation type
Centralized Rules: Rule catalog with consistent error messages
Flexible Configuration: Dynamic rule building from configuration
Module |
+Purpose |
+
|---|---|
|
+TOML configuration loading and validation |
+
|
+Core validation engine and specialized validators |
+
|
+Builds validation rules from configuration |
+
|
+Centralized catalog of validation rules and messages |
+
|
+CLI interface and orchestration |
+
Install commit-check v2.0+:
+pip install commit-check>=2.0.0
+Start with defaults (no configuration needed):
+commit-check --message --branch
+Customize as needed with cchk.toml:
[commit]
+conventional_commits = true
+subject_max_length = 72
+Follow the Migration Guide: See Migration Guide
Test thoroughly: Validate your new configuration before deploying
Configuration Reference - Complete configuration options
Migration Guide - Step-by-step upgrade instructions
CLI Reference - Command-line interface documentation