docs/reference/configuration.md
@commitlint/cli picks up configuration from the following files:
.commitlintrc.commitlintrc.json.commitlintrc.yaml.commitlintrc.yml.commitlintrc.js.commitlintrc.cjs.commitlintrc.mjs.commitlintrc.ts.commitlintrc.cts.commitlintrc.mtscommitlint.config.jscommitlint.config.cjscommitlint.config.mjscommitlint.config.tscommitlint.config.ctscommitlint.config.mtsThe file is expected
Configuration files are resolved using cosmiconfig.
package.jsonYou can add a commitlint field in package.json (or package.yaml) with an object that follows the below structure.
Add the path to the configuration file. Example: commitlint --config commitlint.config.js
const Configuration = {
/*
* Resolve and load @commitlint/config-conventional from node_modules.
* Referenced packages must be installed
*/
extends: ["@commitlint/config-conventional"],
/*
* Resolve and load conventional-changelog-atom from node_modules.
* Referenced packages must be installed
*/
parserPreset: "conventional-changelog-atom",
/*
* Resolve and load @commitlint/format from node_modules.
* Referenced package must be installed
*/
formatter: "@commitlint/format",
/*
* Any rules defined here will override rules from @commitlint/config-conventional
*/
rules: {
"type-enum": [2, "always", ["foo"]],
},
/*
* Array of functions that return true if commitlint should ignore the given message.
* Given array is merged with predefined functions, which consist of matchers like:
*
* - 'Merge pull request', 'Merge X into Y' or 'Merge branch X'
* - 'Revert X'
* - 'v1.2.3' (ie semver matcher)
* - 'Automatic merge X' or 'Auto-merged X into Y'
*
* To see full list, check https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/is-ignored/src/defaults.ts.
* To disable those ignores and run rules always, set `defaultIgnores: false` as shown below.
*/
ignores: [(commit) => commit === ""],
/*
* Whether commitlint uses the default ignore rules, see the description above.
*/
defaultIgnores: true,
/*
* Custom URL to show upon failure
*/
helpUrl:
"https://github.com/conventional-changelog/commitlint/#what-is-commitlint",
/*
* Custom prompt configs
*/
prompt: {
messages: {},
questions: {
type: {
description: "please input type:",
},
},
},
};
export default Configuration;
[!NOTE] CJS format is supported as well:
jsmodule.exports = Configuration;
Configuration can also be a TypeScript file.
Relevant types and enums can be imported from @commitlint/types.
Below you can see main changes from a standard js file:
import type { UserConfig } from "@commitlint/types"; // [!code focus]
import { RuleConfigSeverity } from "@commitlint/types"; // [!code focus]
const Configuration: UserConfig = {
// [!code focus]
extends: ["@commitlint/config-conventional"],
parserPreset: "conventional-changelog-atom",
formatter: "@commitlint/format",
rules: {
"type-enum": [RuleConfigSeverity.Error, "always", ["foo"]], // [!code focus]
},
// ...
};
export default Configuration;
Every commitlint configuration can extend other commitlint configurations.
Specify configurations to extend via the .extends key, using ids
that can be resolved by the node resolve algorithm.
This means installed npm packages and local files can be used.
npm install --save-dev commitlint-config-lerna @commitlint/config-conventional
::: code-group
export default {
extends: [
'lerna' // prefixed with commitlint-config-*,
'@commitlint/config-conventional' // scoped packages are not prefixed
]
}
More information can be found in the Concepts – shareable config section.
The parser preset controls how commit messages are parsed into their component parts (type, scope, subject, body, footer, etc.). By default, commitlint does not ship with a parser preset — it falls back to conventional-changelog-angular defaults. When you extend @commitlint/config-conventional, the conventional-changelog-conventionalcommits preset is applied, which follows the Conventional Commits specification.
You can override the parser preset using the parserPreset property. It accepts:
parserOpts property for inline configurationnpm install --save-dev conventional-changelog-atom
::: code-group
export default {
parserPreset: "conventional-changelog-atom",
};
:::
::: code-group
export default {
parserPreset: "./parser-preset",
};
export default {
parserOpts: {
headerPattern: /^(\w*)\((\w*)\)-(\w*)\s(.*)$/,
headerCorrespondence: ["type", "scope", "ticket", "subject"],
},
};
:::
parserOptsYou can also pass parserOpts directly without a separate file. This is useful for small adjustments like custom issue prefixes:
::: code-group
export default {
parserPreset: {
parserOpts: {
issuePrefixes: ["PROJ-", "JIRA-"],
},
},
};
:::
parserOptsThe parser is powered by conventional-commits-parser. Common options include:
| Option | Description |
|---|---|
headerPattern | Regex to match the commit header (type, scope, subject) |
headerCorrespondence | Array of field names matching the capture groups in headerPattern |
issuePrefixes | Prefixes to match issue references (e.g. ["#", "PROJ-"]) |
noteKeywords | Keywords that mark footer notes (e.g. ["BREAKING CHANGE"]) |
breakingHeaderPattern | Regex to detect breaking changes in the header (e.g. the ! marker) |
For the complete list of options, see the conventional-commits-parser documentation.
presetConfigWhen using a preset like conventional-changelog-conventionalcommits, you can pass a presetConfig object to customize the preset's behavior without replacing the entire parser configuration. This is commonly used to set commit types that appear in generated changelogs:
::: code-group
export default {
parserPreset: {
name: "conventional-changelog-conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
{ type: "chore", hidden: true },
],
},
},
};
:::
The available presetConfig options depend on the preset you are using. See the conventional-changelog-conventionalcommits documentation for details.
If you use semantic-release, both commitlint and semantic-release can share the same conventional-changelog-conventionalcommits preset. Keeping parserOpts and presetConfig consistent across both tools ensures that commits parsed during linting match what semantic-release uses for versioning and changelog generation:
::: code-group
export default {
extends: ["@commitlint/config-conventional"],
parserPreset: {
name: "conventional-changelog-conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
};
:::
export default {
plugins: [
[
"@semantic-release/commit-analyzer",
{
preset: "conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
],
[
"@semantic-release/release-notes-generator",
{
preset: "conventionalcommits",
presetConfig: {
types: [
{ type: "feat", section: "Features" },
{ type: "fix", section: "Bug Fixes" },
{ type: "docs", section: "Documentation", hidden: false },
],
},
},
],
],
};
Commitlint can output the issues encountered in different formats, if necessary. Use ids resolvable by the node resolve algorithm.
export default {
formatter: "@commitlint/format",
};
Refer to Rules for a complete list of available rules.
Config command-line submit interaction, works with @commitlint/cz-commitlint.
Refer to Prompt Config for details.