Configuration
Configuration File
cargo-commitlint looks for configuration in the following locations (in order):
commitlint.tomlor.commitlint.toml.commitlintrc.toml,.commitlintrc.json,.commitlintrc.yamlor.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 typestype-case- Case requirement for the typetype-empty- Whether the type may be emptytype-max-length / type-min-length- Length bounds for the typescope-enum- Allowed scopesscope-case- Case requirement for the scopescope-empty- Whether the scope may be emptyscope-max-length / scope-min-length- Length bounds for the scope
Subject & Header
subject-case- Allowed case formats for the subjectsubject-empty- Whether the subject may be emptysubject-full-stop- Trailing punctuation on the subjectsubject-exclamation-mark- The breaking-change ! markersubject-max-length / subject-min-length- Length bounds for the subjectheader-max-length- Maximum header length (default: 100)header-min-length- Minimum header lengthheader-case / header-full-stop / header-trim- Header case, punctuation and whitespace
Body, Footer & Other
body-leading-blank- Require a blank line before the bodybody-max-line-length- Maximum line length in the body (default: 100)body-case / body-empty / body-full-stop- Body case, presence and punctuationbody-max-length / body-min-length- Length bounds for the bodyfooter-leading-blank- Require a blank line before the footerfooter-max-line-length- Maximum line length in the footerfooter-empty / footer-max-length / footer-min-length- Footer presence and length boundsreferences-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>.*)$"