commitlint

commitlint is a tool used to check if commit messages adhere to the conventional commit format.

The general pattern is: type(scope?): subject

• scope is optional and supports multiple scopes using delimiters like /, \, or ,.
• Common types (based on @commitlint/config-conventional) include: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, and test.

Examples:

• chore: run tests on travis ci
• fix(server): send cors headers
• feat(blog): add comment section

The minimum supported Node.js version has changed across major releases. Ensure your environment meets the requirements for your installed version:

• v18.0.0 and later: Requires Node.js v18 or higher.
• v17.0.0 to v17.x.x: Requires Node.js v14 or higher.
• v13.0.0 to v16.x.x: Requires Node.js v12 or higher.

If your rule configuration needs to be dynamic or depends on external data, you can define a rule as a function instead of a plain array. commitlint supports both synchronous functions and asynchronous functions (returning a Promise) that return the rule configuration array [level, applicable, value].

Use a synchronous function for simple dynamic logic and an async function if you need to perform I/O or fetch configuration from an external source.

// Function returning array
export default {
  rules: {
    "header-max-length": () => [0, "always", 72],
  },
};

// Async function returning array
export default {
  rules: {
    "header-max-length": async () => [0, "always", 72],
  },
};

Every commitlint configuration can inherit from others using the extends key. This supports:

• npm packages: Use the package ID (e.g., '@commitlint/config-conventional'). Note that some packages like lerna might be prefixed as commitlint-config-lerna.
• Local files: Use relative paths to other configuration files (e.g., './commitlint.base.js').

Rules defined in your local configuration will override rules inherited from extended configurations.

export default {
  extends: [
    'lerna', // prefixed automatically
    '@commitlint/config-conventional' // scoped package
  ]
}

Commitlint supports commits that target multiple scopes. To specify multiple scopes, you must separate the segments using delimiters.

By default, the supported delimiters are:

• / (forward slash)
• \ (backslash)
• , (comma)

Example of a multi-scope commit: feat(api,auth): add login endpoint

You can customize the allowed set of delimiters using the scope-delimiter-style rule.

type(scope1,scope2): subject

When working with scoped npm packages, you have two ways to extend them in your extends array:

1. Full Package Name: Provide the exact name of the package (e.g., @scope/commitlint-config-name).
2. Scope Shortcut: Provide only the scope. commitlint will automatically look for a package following the pattern <scope>/commitlint-config.

If your package does not follow the exact <scope>/commitlint-config pattern, you must provide the full package name.

// Option 1: Full package name
export default {
  extends: ["@commitlint/config-conventional"],
};

// Option 2: Scope shortcut (resolves to @coolcompany/commitlint-config)
export default {
  extends: ["@coolcompany"],
};