# Configuration ## Config via file `@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.mts` - `commitlint.config.js` - `commitlint.config.cjs` - `commitlint.config.mjs` - `commitlint.config.ts` - `commitlint.config.cts` - `commitlint.config.mts` The file is expected - to contain valid JavaScript / TypeScript - export a configuration object - adhere to the schema outlined below Configuration files are resolved using [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). ## Config via `package.json` You can add a `commitlint` field in `package.json` (or [`package.yaml`](https://github.com/pnpm/pnpm/pull/1799)) with an object that follows the below structure. ## Config option CLI Add the path to the configuration file. Example: `commitlint --config commitlint.config.js` ## Configuration object example ```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: > > ```js > module.exports = Configuration; > ``` ### TypeScript 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: ```ts 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; ``` ## Shareable 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. :::tabs == npm ```sh npm install --save-dev commitlint-config-lerna @commitlint/config-conventional ``` ::: code-group ```js [commitlint.config.js] export default { extends: [ 'lerna' // prefixed with commitlint-config-*, '@commitlint/config-conventional' // scoped packages are not prefixed ] } ``` == local ::: code-group ```js [commitlint.config.js] export default { extends: ["./commitlint.base.js", "./commitlint.types.js"], }; ``` ```js [commitlint.types.js] // will be picked up by commitlint.config.js export default { rules: { "type-enum": [2, "always", ["foo"]], }, }; ``` ```js [commitlint.base.js] // will be picked up by commitlint.config.js export default { extends: ["@commitlint/config-conventional"], // extends can be nested parserPreset: "conventional-changelog-atom", }; ``` ::: More information can be found in the [Concepts – shareable config section](/concepts/shareable-config). ## Parser presets 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`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) defaults. When you extend `@commitlint/config-conventional`, the [`conventional-changelog-conventionalcommits`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits) preset is applied, which follows the [Conventional Commits specification](https://www.conventionalcommits.org/). You can override the parser preset using the `parserPreset` property. It accepts: - A **string** referencing an npm package or local file (resolved via Node's module resolution) - An **object** with a `parserOpts` property for inline configuration ### Using an npm package ```sh npm install --save-dev conventional-changelog-atom ``` ::: code-group ```js [commitlint.config.js] export default { parserPreset: "conventional-changelog-atom", }; ``` ::: ### Using a local file ::: code-group ```js [commitlint.config.js] export default { parserPreset: "./parser-preset", }; ``` ```js [parser-preset.js] export default { parserOpts: { headerPattern: /^(\w*)\((\w*)\)-(\w*)\s(.*)$/, headerCorrespondence: ["type", "scope", "ticket", "subject"], }, }; ``` ::: ### Inline `parserOpts` You can also pass `parserOpts` directly without a separate file. This is useful for small adjustments like custom issue prefixes: ::: code-group ```js [commitlint.config.js] export default { parserPreset: { parserOpts: { issuePrefixes: ["PROJ-", "JIRA-"], }, }, }; ``` ::: ### Common `parserOpts` The parser is powered by [`conventional-commits-parser`](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/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) | With the default parser, if a header with non-ASCII characters gets no type, commitlint tries again with a `headerPattern` or `breakingHeaderPattern` that starts with `^(\w*)` rewritten to read the type as letters, combining marks, numbers and `_` of any script (and the `u` flag added), so `功能: 新增登录` has the type `功能`. The result of the first try is kept when it already has a type, and patterns that use the `u` or `v` flag or start differently are used as written. A custom `parser` is called once with the patterns as given. For the complete list of options, see the [`conventional-commits-parser` documentation](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#options). ### `presetConfig` When 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 ```js [commitlint.config.js] 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-conventionalcommits#preset-configuration) for details. ### Usage with semantic-release If you use [semantic-release](https://github.com/semantic-release/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 ```js [commitlint.config.js] 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 }, ], }, }, }; ``` ::: ```js [.releaserc.js] 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 }, ], }, }, ], ], }; ``` ## Formatter Commitlint can output the issues encountered in different formats, if necessary. Use ids resolvable by the node resolve algorithm. ```js export default { formatter: "@commitlint/format", }; ``` ## Rules Refer to [Rules](/reference/rules.md) for a complete list of available rules. ## Prompt Config command-line submit interaction, works with `@commitlint/cz-commitlint`. Refer to [Prompt Config](/reference/prompt.md) for details.