Configuration

Configuration File

cargo-commitlint looks for configuration in the following locations (in order):

  • commitlint.toml or .commitlint.toml
  • .commitlintrc.toml, .commitlintrc.json, .commitlintrc.yaml or .commitlintrc.yml
  • .cargo/commitlint.toml

If no configuration file is found, default settings are used.

Configuration Options

Rule Shape

Every rule is configured the same way:

[rules.type-enum]
level = 2             # 0 = disabled, 1 = warning, 2 = error
applicable = "always" # or "never", which inverts the rule
value = ["feat", "fix"]

applicable = "never" inverts the check, so type-empty with never means the type must not be empty. Omit value when a rule takes none.

Type & Scope

  • type-enum - Allowed commit types
  • type-case - Case requirement for the type
  • type-empty - Whether the type may be empty
  • type-max-length / type-min-length - Length bounds for the type
  • scope-enum - Allowed scopes
  • scope-case - Case requirement for the scope
  • scope-empty - Whether the scope may be empty
  • scope-max-length / scope-min-length - Length bounds for the scope

Subject & Header

  • subject-case - Allowed case formats for the subject
  • subject-empty - Whether the subject may be empty
  • subject-full-stop - Trailing punctuation on the subject
  • subject-exclamation-mark - The breaking-change ! marker
  • subject-max-length / subject-min-length - Length bounds for the subject
  • header-max-length - Maximum header length (default: 100)
  • header-min-length - Minimum header length
  • header-case / header-full-stop / header-trim - Header case, punctuation and whitespace

Body, Footer & Other

  • body-leading-blank - Require a blank line before the body
  • body-max-line-length - Maximum line length in the body (default: 100)
  • body-case / body-empty / body-full-stop - Body case, presence and punctuation
  • body-max-length / body-min-length - Length bounds for the body
  • footer-leading-blank - Require a blank line before the footer
  • footer-max-line-length - Maximum line length in the footer
  • footer-empty / footer-max-length / footer-min-length - Footer presence and length bounds
  • references-empty / signed-off-by / trailer-exists - Issue references and required trailers

Run cargo commitlint print-config to see all 36 rules with their resolved defaults.

Complete Example

# Skip validation for commits matching these regex patterns
ignores = ["^Merge branch", "^Revert "]

# Built-in ignores for merge, revert and squash commits
defaultIgnores = true

[rules.type-enum]
level = 2
applicable = "always"
value = ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"]

[rules.type-case]
level = 2
applicable = "always"
value = ["lower-case"]

# "never" inverts it: the type must NOT be empty
[rules.type-empty]
level = 2
applicable = "never"

[rules.subject-case]
level = 2
applicable = "always"
value = ["lower-case", "sentence-case"]

[rules.header-max-length]
level = 2
applicable = "always"
value = 100

# level 1 warns without failing the commit
[rules.body-leading-blank]
level = 1
applicable = "always"

[parser]
header_pattern = "^(?P<type>\w+)(?:\((?P<scope>[^)]+)\))?(?P<breaking>!)?:\s*(?P<subject>.*)$"