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.

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

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"

Example Configuration¶

[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 - bypass checks for these commit/co-authors
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

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:

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¶