Configuration

commit-check can be configured in three ways with the following priority (highest to lowest):

1. Command-line arguments (--subject-imperative=true)
2. Environment variables (CCHK_SUBJECT_IMPERATIVE=true)
3. Configuration files (cchk.toml or commit-check.toml)
4. Built-in defaults

This flexibility allows you to:

• Use configuration files for project-wide settings
• Override with environment variables in CI/CD pipelines
• Override specific settings via CLI for one-off checks
• Use without any configuration files (relies on defaults)

Configuration Files

commit-check configuration files support the TOML format. See cchk.toml for an example configuration.

Default Behavior

• When no configuration file exists, commit-check uses sensible defaults with minimal restrictions.
• Enforced by default: the Conventional Commits format (CC001), the Conventional Branch format (CC201), the subject length limits of 5–80 characters (CC004, CC005), and the author name and email patterns (CC101, CC102).
• Off by default: subject capitalization, imperative mood, body and signoff requirements, rebase requirements, and every allow_* restriction.

See rules for the default state of every rule.

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 or in the .github folder.

Configuration File Locations

commit-check searches for configuration files in the following order (first found is used):

1. cchk.toml (root directory)
2. commit-check.toml (root directory)
3. .github/cchk.toml
4. .github/commit-check.toml

GitHub Best Practice

Placing configuration files in the .github folder helps keep your repository root clean and follows GitHub conventions used by tools like Dependabot and Renovate.

IDE Autocompletion

commit-check's TOML schema is published on SchemaStore, so editors like VS Code (via Even Better TOML), PyCharm, and IntelliJ provide autocompletion, validation, and documentation tooltips for cchk.toml out of the box — no manual schema path configuration needed.

Organization-Level Configuration (inherit_from)

For organizations that want to share a common base configuration across many repositories, commit-check supports an inherit_from directive at the top level of your TOML config file.

How it works:

1. The inherit_from value can be a github: shorthand, a local file path, or an HTTPS URL.
2. The parent (inherited) configuration is loaded first.
3. Local settings in the current config file override the parent values.
4. The inherit_from key itself is not passed to the validation engine.

Example — inherit from a GitHub repository (recommended):

# .github/cchk.toml
inherit_from = "github:my-org/.github:cchk.toml"

[commit]
subject_max_length = 72  # Overrides parent value

GitHub shorthand format:

• github:owner/repo:path/to/cchk.toml — uses HEAD (default branch)
• github:owner/repo@main:path/to/cchk.toml — pins to the main branch

Example — inherit from a local file:

# repo/.github/cchk.toml
inherit_from = "../../shared/org-cchk.toml"

[commit]
allow_wip_commits = true  # Override for this project only

Example — inherit from an HTTPS URL:

# .github/cchk.toml
inherit_from = "https://example.com/shared/cchk.toml"

Note

If the inherit_from target is unreachable or the format is unrecognized, commit-check silently ignores the inheritance and uses only the local configuration. HTTP (non-TLS) URLs are rejected for security.

Example Configuration

[commit]
# https://www.conventionalcommits.org
conventional_commits = true
# message_pattern = ""     # Optional - custom regex (overrides conventional_commits)
subject_capitalized = false
subject_imperative = false
subject_max_length = 80    # Default - set to your own limit
subject_min_length = 5     # Default - set to your own minimum
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 - bypass checks for these commit/co-authors
require_signed_off_by = false
ai_attribution = "forbid"  # "ignore" (default) or "forbid" — rejects AI tool trailers

[push]
# Block force pushes when used as a pre-push hook or with --no-force-push
allow_force_push = true  # Set to false to block force pushes

[branch]
# https://conventionalbranch.org
conventional_branch = true
# Optional: defaults are a superset of the Conventional Branch spec — the
# spec types plus Conventional Commit types, AI agent prefixes and bot
# prefixes (see the Options table below for the full list). Omit this
# option to use the defaults, or set your own list for a strict subset.
allow_branch_types = [
    "feature",
    "bugfix",
    "hotfix",
    "release",
    "chore",
    "feat",
    "fix",
    "build",
    "ci",
    "docs",
    "perf",
    "refactor",
    "style",
    "test",
]
# 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

Command-Line Arguments

All configuration options can be specified via command-line arguments, which take precedence over environment variables and configuration files.

Syntax:

• Boolean options: --option-name=true or --option-name=false
• Integer options: --option-name=80
• List options: --option-name=value1,value2,value3 (comma-separated)
• String options: --option-name=value

Examples:

# Disable imperative mood check
commit-check --message --subject-imperative=false

# Set custom subject length limit
commit-check --message --subject-max-length=72

# Restrict allowed commit types
commit-check --message --allow-commit-types=feat,fix,docs

# Combine multiple options
commit-check --message --subject-imperative=true --subject-max-length=50 --allow-commit-types=feat,fix

# Branch configuration via CLI
commit-check --branch --allow-branch-types=feature,bugfix,hotfix

Pre-commit Hook Usage:

The primary use case for CLI arguments is configuring commit-check in .pre-commit-config.yaml without requiring a TOML file:

repos:
  - repo: https://github.com/commit-check/commit-check
    rev: v2.5.0
    hooks:
      - id: check-message
        args:
          - --subject-imperative=false
          - --subject-max-length=100
          - --allow-merge-commits=false

Environment Variables

Configuration can also be set via environment variables with the CCHK_ prefix. This is useful for CI/CD pipelines and temporary overrides.

Naming Convention:

• Convert option name to uppercase
• Replace hyphens with underscores
• Add CCHK_ prefix

Examples:

# Set boolean options
export CCHK_SUBJECT_IMPERATIVE=true
export CCHK_SUBJECT_CAPITALIZED=false

# Set integer options
export CCHK_SUBJECT_MAX_LENGTH=72
export CCHK_SUBJECT_MIN_LENGTH=10

# Set list options (comma-separated)
export CCHK_ALLOW_COMMIT_TYPES=feat,fix,docs,chore
export CCHK_ALLOW_BRANCH_TYPES=feature,bugfix,hotfix

# Set string options
export CCHK_REQUIRE_REBASE_TARGET=main

# Use in CI/CD
CCHK_SUBJECT_MAX_LENGTH=100 commit-check --message

Complete Mapping:

TOML Config	Environment Variable	CLI Argument
conventional_commits = true	CCHK_CONVENTIONAL_COMMITS=true	--conventional-commits=true
message_pattern = "^PROJ-\\d+: .+"	CCHK_MESSAGE_PATTERN=^PROJ-\\d+: .+	N/A (config file only)
subject_capitalized = false	CCHK_SUBJECT_CAPITALIZED=false	--subject-capitalized=false
subject_imperative = true	CCHK_SUBJECT_IMPERATIVE=true	--subject-imperative=true
subject_max_length = 80	CCHK_SUBJECT_MAX_LENGTH=80	--subject-max-length=80
subject_min_length = 5	CCHK_SUBJECT_MIN_LENGTH=5	--subject-min-length=5
allow_commit_types = ["feat", "fix"]	CCHK_ALLOW_COMMIT_TYPES=feat,fix	--allow-commit-types=feat,fix
allow_merge_commits = true	CCHK_ALLOW_MERGE_COMMITS=true	--allow-merge-commits=true
allow_revert_commits = true	CCHK_ALLOW_REVERT_COMMITS=true	--allow-revert-commits=true
allow_empty_commits = false	CCHK_ALLOW_EMPTY_COMMITS=false	--allow-empty-commits=false
allow_fixup_commits = true	CCHK_ALLOW_FIXUP_COMMITS=true	--allow-fixup-commits=true
allow_wip_commits = false	CCHK_ALLOW_WIP_COMMITS=false	--allow-wip-commits=false
require_body = false	CCHK_REQUIRE_BODY=false	--require-body=false
require_signed_off_by = false	CCHK_REQUIRE_SIGNED_OFF_BY=false	--require-signed-off-by=false
ignore_authors = ["bot"]	CCHK_IGNORE_AUTHORS=bot,user	--ignore-authors=bot,user
author_email_pattern=^.+@example\.com$	CCHK_AUTHOR_EMAIL_PATTERN=^.+@example\.com$	--author-email-pattern=^.+@example\.com$
author_name_pattern=^.+ .+$	CCHK_AUTHOR_NAME_PATTERN=^.+ .+$	--author-name-pattern=^.+ .+$
conventional_branch = true	CCHK_CONVENTIONAL_BRANCH=true	--conventional-branch=true
allow_branch_types = ["feature"]	CCHK_ALLOW_BRANCH_TYPES=feature,bugfix	--allow-branch-types=feature,bugfix
allow_branch_names = ["develop"]	CCHK_ALLOW_BRANCH_NAMES=develop,staging	--allow-branch-names=develop,staging
require_rebase_target = "main"	CCHK_REQUIRE_REBASE_TARGET=main	--require-rebase-target=main
allow_force_push = true	CCHK_ALLOW_FORCE_PUSH=true	--no-force-push (sets allow_force_push to false)
ai_attribution = "forbid"	CCHK_AI_ATTRIBUTION=forbid	--ai-attribution=forbid
ignore_authors = ["bot"] (in branch section)	CCHK_BRANCH_IGNORE_AUTHORS=bot,user	--branch-ignore-authors=bot,user

Configuration Priority Example

When the same option is specified in multiple places, the priority determines which value is used:

# In cchk.toml:
# subject_max_length = 100

# Set via environment:
export CCHK_SUBJECT_MAX_LENGTH=80

# Override via CLI:
commit-check --message --subject-max-length=50

# Result: subject_max_length = 50 (CLI wins)

Options Table Description

Section	Option	Type	Default	Description
commit	conventional_commits	bool	true	Enforce Conventional Commits specification.
commit	message_pattern	str	"" (disabled)	Custom regex pattern for commit message validation. When set, this pattern replaces the auto-generated Conventional Commits regex entirely, making it possible to enforce custom formats such as JIRA smart commits (e.g., "^PROJ-\\d+: .+"). When message_pattern is set (non-empty) it takes precedence over conventional_commits.
commit	subject_capitalized	bool	false	Subject must start with a capital letter.
commit	subject_imperative	bool	false	Subject must be in imperative mood. Forms of verbs can be found at imperatives.py
commit	subject_max_length	int	80	Maximum length of the subject line.
commit	subject_min_length	int	5	Minimum length of the subject line.
commit	allow_commit_types	list[str]	["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci"]	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	true	Allow empty commits.
commit	allow_fixup_commits	bool	true	Allow fixup commits (e.g., "fixup! ").
commit	allow_wip_commits	bool	true	Allow work-in-progress commits (e.g., "WIP: ").
commit	require_body	bool	false	Require a body in the commit message.
commit	ignore_authors	list[str]	[] (none ignored)	List of commit authors or co-authors (Co-authored-by: lines) to bypass all commit checks. Useful for bots (e.g., "dependabot[bot]", "coderabbitai[bot]").
commit	author_email_pattern	str	^.+@.+$	Custom regex for the author email check. When empty, the built-in default pattern is used. This option only takes effect when the author_email check is enabled (-e / --author-email).
commit	author_name_pattern	str	"" (built-in default)	Custom regex for the author name check. When empty, the built-in default pattern is used (it is not disabled). This option only takes effect when the author_name check is enabled (-n / --author-name).
commit	require_signed_off_by	bool	false	Require "Signed-off-by" line in the commit message footer.
commit	ai_attribution	str	"ignore"	AI attribution policy. "forbid" rejects any commit containing known AI tool signatures (Claude Code, Copilot, Codex, Gemini, Cursor, Devin, Aider, Windsurf, Tabby, and generic AI model patterns). "ignore" disables the check. This feature is a response to the industry-wide discussion on AI disclosure in open source (Linux kernel Assisted-by: trailer, CPython, VS Code, Apache, Fedora policies).
branch	conventional_branch	bool	true	Enforce Conventional Branch specification.
branch	allow_branch_types	list[str]	["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "style", "test", "ai", "claude", "codex", "copilot", "cursor", "dependabot", "renovate"]	Allowed branch types when conventional_branch is true. The default is a superset of the Conventional Branch spec: the spec types (feature, bugfix, hotfix, release, chore) plus the Conventional Commit types (build, ci, docs, perf, refactor, style, test), AI agent prefixes (ai, claude, codex, copilot, cursor) and bot prefixes (dependabot, renovate). For strict spec-only validation, set this option explicitly (e.g. ["feature", "bugfix", "hotfix", "release", "chore"]).
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	"" (no requirement)	Target branch for rebase requirement. If not set, no rebase validation is performed.
push	allow_force_push	bool	true	Allow force pushes. Set to false to block force pushes when used as a pre-push hook or with --no-force-push.
branch	ignore_authors	list[str]	[] (none ignored)	List of authors to ignore (i.e., always allow).