Commitlint

Validate commit messages against Conventional Commits format using commitlint configuration and rules.

When to Use This Skill

Use this skill when:

• Setting up commitlint for a repository
• Configuring commitlint rules and shareable configurations
• Integrating commitlint with pre-commit hooks or CI/CD pipelines
• Extracting rules from commitlint config to generate LLM prompts for commit message generation
• Validating commit messages programmatically
• Troubleshooting commitlint configuration or validation errors
• Understanding commitlint rule syntax and severity levels
• Detecting commitlint configuration files in a repository

Core Capabilities

Configuration Detection

Commitlint uses cosmiconfig to find configuration files in this priority order:

Dedicated config files:

.commitlintrc
.commitlintrc.json
.commitlintrc.yaml
.commitlintrc.yml
.commitlintrc.js
.commitlintrc.cjs
.commitlintrc.mjs
.commitlintrc.ts
.commitlintrc.cts
commitlint.config.js
commitlint.config.cjs
commitlint.config.mjs
commitlint.config.ts
commitlint.config.cts

Package files:

• package.json with commitlint field
• package.yaml (PNPM) with commitlint field

Configuration Formats

JavaScript ES Modules (Recommended):

// commitlint.config.js or commitlint.config.mjs
export default {
  extends: ['@commitlint/config-conventional'],
};

TypeScript:

// commitlint.config.ts
import type { UserConfig } from '@commitlint/types';
import { RuleConfigSeverity } from '@commitlint/types';

const config: UserConfig = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [RuleConfigSeverity.Error, 'always', ['feat', 'fix', 'docs']],
  },
};

export default config;

JSON:

{
  "extends": ["@commitlint/config-conventional"]
}

YAML:

extends:
  - "@commitlint/config-conventional"

Rule Configuration

Rules are configured as arrays: [level, applicability, value]

Severity Levels:

Level	Meaning	TypeScript Enum
0	Disabled	RuleConfigSeverity.Disabled
1	Warning	RuleConfigSeverity.Warning
2	Error	RuleConfigSeverity.Error

Applicability:

• 'always' - Rule must match
• 'never' - Rule must not match

Example rules:

rules: {
  // Error if type is not in enum
  'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']],

  // Error if type is empty
  'type-empty': [2, 'never'],

  // Error if subject is empty
  'subject-empty': [2, 'never'],

  // Error if header exceeds 100 chars
  'header-max-length': [2, 'always', 100],

  // Error if subject ends with period
  'subject-full-stop': [2, 'never', '.'],

  // Warning if body doesn't have leading blank line
  'body-leading-blank': [1, 'always'],
}

Common Configurations

@commitlint/config-conventional

The most widely used shareable configuration. Default error-level rules:

Rule	Configuration	Pass Example	Fail Example
type-enum	['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test']	fix: message	foo: message
type-case	'lowerCase'	fix: message	FIX: message
type-empty	never	fix: message	: message
subject-case	never + ['sentence-case', 'start-case', 'pascal-case', 'upper-case']	fix: some message	fix: Some Message
subject-empty	never	fix: message	fix:
subject-full-stop	never, '.'	fix: message	fix: message.
header-max-length	100	Short header	Header > 100 chars
body-leading-blank	always (warning)	Blank line before body	No blank line
body-max-line-length	100	Lines <= 100 chars	Line > 100 chars
footer-leading-blank	always (warning)	Blank line before footer	No blank line
footer-max-line-length	100	Lines <= 100 chars	Line > 100 chars

Complete Configuration Schema

// commitlint.config.js
export default {
  // Extend shareable configs (resolved via node resolution)
  extends: ['@commitlint/config-conventional'],

  // Parser preset for parsing commit messages
  parserPreset: 'conventional-changelog-atom',

  // Output formatter
  formatter: '@commitlint/format',

  // Custom rules (override inherited rules)
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
  },

  // Functions that return true to ignore specific commits
  // Merged with default ignores (merge commits, reverts, semver tags)
  ignores: [(commit) => commit.includes('WIP')],

  // Whether to use default ignore patterns
  // Default patterns: 'Merge pull request', 'Revert X', 'v1.2.3', etc.
  defaultIgnores: true,

  // Custom help URL shown on failure
  helpUrl: 'https://example.com/commit-guidelines',

  // Prompt configuration (for @commitlint/cz-commitlint)
  prompt: {
    messages: {},
    questions: {
      type: {
        description: 'Select the type of change:',
      },
    },
  },
};

CLI Usage

Installation

# npm
npm install -D @commitlint/cli @commitlint/config-conventional

# yarn
yarn add -D @commitlint/cli @commitlint/config-conventional

# pnpm
pnpm add -D @commitlint/cli @commitlint/config-conventional

Common Commands

# Lint the last commit
npx commitlint --last

# Lint a range of commits
npx commitlint --from HEAD~5

# Lint from a specific commit
npx commitlint --from abc1234

# Lint message from stdin
echo "feat: add feature" | npx commitlint

# Lint message from file
npx commitlint < .git/COMMIT_EDITMSG

# Lint with edit flag (reads .git/COMMIT_EDITMSG)
npx commitlint --edit

# Lint with custom config path
npx commitlint --config ./custom-commitlint.config.js

# Print resolved config
npx commitlint --print-config

# Strict mode (warnings become exit code 2)
npx commitlint --last --strict

Exit Codes

Code	Meaning
0	Success (no errors)
1	Lint errors found
2	Warnings found (strict mode only)
3	Errors found (strict mode)
9	Config file missing (with -g flag)

Rule Reference

Type Rules

Rule	Condition	Default Applicability
type-enum	type is found in value	always
type-case	type is in case value	always, 'lower-case'
type-empty	type is empty	never
type-max-length	type has value or less characters	always, Infinity
type-min-length	type has value or more characters	always, 0

Subject Rules

Rule	Condition	Default Applicability
subject-case	subject is in case value	always
subject-empty	subject is empty	never
subject-full-stop	subject ends with value	never, '.'
subject-max-length	subject has value or less characters	always, Infinity
subject-min-length	subject has value or more characters	always, 0
subject-exclamation-mark	subject has exclamation before :	never

Scope Rules

Rule	Condition	Default Applicability
scope-enum	scope is found in value	always, []
scope-case	scope is in case value	always, 'lower-case'
scope-empty	scope is empty	never
scope-max-length	scope has value or less characters	always, Infinity
scope-min-length	scope has value or more characters	always, 0

Header Rules

Rule	Condition	Default Applicability
header-case	header is in case value	always, 'lower-case'
header-full-stop	header ends with value	never, '.'
header-max-length	header has value or less characters	always, 72
header-min-length	header has value or more characters	always, 0
header-trim	header has no leading/trailing whitespace	always

Body Rules

Rule	Condition	Default Applicability
body-leading-blank	body begins with blank line	always
body-empty	body is empty	never
body-max-length	body has value or less characters	always, Infinity
body-max-line-length	body lines have value or less characters (URLs excluded)	always, Infinity
body-min-length	body has value or more characters	always, 0
body-case	body is in case value	always, 'lower-case'
body-full-stop	body ends with value	never, '.'

Footer Rules

Rule	Condition	Default Applicability
footer-leading-blank	footer begins with blank line	always
footer-empty	footer is empty	never
footer-max-length	footer has value or less characters	always, Infinity
footer-max-line-length	footer lines have value or less characters	always, Infinity
footer-min-length	footer has value or more characters	always, 0

Case Values

For rules that check case (*-case):

[
  'lower-case',    // lowercase
  'upper-case',    // UPPERCASE
  'camel-case',    // camelCase
  'kebab-case',    // kebab-case
  'pascal-case',   // PascalCase
  'sentence-case', // Sentence case
  'snake-case',    // snake_case
  'start-case',    // Start Case
]

Programmatic Usage

Load Configuration

import load from '@commitlint/load';

async function getCommitlintConfig() {
  const config = await load();
  console.log(config.rules);
  return config;
}

Validate Message

import load from '@commitlint/load';
import lint from '@commitlint/lint';

async function validateMessage(message) {
  const config = await load();
  const result = await lint(message, config.rules);

  return {
    valid: result.valid,
    errors: result.errors,
    warnings: result.warnings,
  };
}

LLM Integration Patterns

Extract Rules for Prompt Generation

Generate LLM-friendly constraints from commitlint config:

def extract_rules_for_prompt(config: dict) -> str:
    """Extract commitlint rules into LLM-friendly format."""
    rules = config.get("rules", {})
    prompt_parts = []

    # Extract type-enum if present
    if "type-enum" in rules:
        level, applicability, types = rules["type-enum"]
        if level > 0 and applicability == "always":
            prompt_parts.append(f"Allowed commit types: {', '.join(types)}")

    # Extract scope-enum if present
    if "scope-enum" in rules:
        level, applicability, scopes = rules["scope-enum"]
        if level > 0 and applicability == "always" and scopes:
            prompt_parts.append(f"Allowed scopes: {', '.join(scopes)}")

    # Extract header-max-length
    if "header-max-length" in rules:
        level, applicability, length = rules["header-max-length"]
        if level > 0:
            prompt_parts.append(f"Header must be {length} characters or less")

    # Extract subject-case
    if "subject-case" in rules:
        level, applicability, cases = rules["subject-case"]
        if level > 0 and applicability == "never":
            prompt_parts.append(f"Subject must NOT use: {', '.join(cases)}")

    return "\n".join(prompt_parts)

Validation Loop

import subprocess


async def validate_with_commitlint(message: str, cwd: Path | None = None) -> tuple[bool, list[str]]:
    """
    Validate commit message with commitlint.

    Args:
        message: The commit message to validate
        cwd: Working directory (defaults to current directory)

    Returns:
        Tuple of (is_valid, error_messages)
    """
    result = subprocess.run(["npx", "commitlint"], input=message, capture_output=True, text=True, cwd=cwd)

    if result.returncode == 0:
        return True, []

    # Parse errors from stderr
    errors = [line.strip() for line in result.stderr.split("\n") if line.strip()]
    return False, errors

Validation loop pattern:

1. LLM generates commit message based on diff and rules
2. Run commitlint on generated message
3. If validation fails, feed errors back to LLM with context
4. Retry (max 3 times by default)
5. Return final message (valid or best effort after retries)

Common Issues

Node v24 ESM issues:

Use .mjs extension for ES modules config, or add "type": "module" to package.json

Missing extends:

Config without extends or rules fails with "Please add rules" error. Include at least one:

export default {
  extends: ['@commitlint/config-conventional'],
};

Empty config error:

Config file must have at least extends or rules defined.

Scope enum empty array:

scope-enum with [] passes all scopes. Use specific array to restrict:

rules: {
  'scope-enum': [2, 'always', ['api', 'ui', 'docs']],
}

Subject case trap:

@commitlint/config-conventional uses never with specific cases, meaning those cases are forbidden (not required):

// This forbids sentence-case, start-case, pascal-case, upper-case
'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']]

Pre-commit Integration

For pre-commit hook integration with commitlint, configure your hook manager directly. If your workspace includes an installed pre-commit plugin, you can use that for hook setup guidance.

Conventional Commits Reference

For Conventional Commits format specification and examples, use the reference in this document. If your workspace includes an installed Conventional Commits plugin, you can defer to it for additional examples and messaging patterns.

References

Official Documentation

• Commitlint Official Site (accessed 2025-01-15)
• Configuration Reference (accessed 2025-01-15)
• Rules Reference (accessed 2025-01-15)
• CLI Reference (accessed 2025-01-15)
• Getting Started Guide (accessed 2025-01-15)
• GitHub Repository (accessed 2025-01-15)

Related Specifications

• Conventional Commits - Commit message format specification
• Cosmiconfig - Configuration file discovery mechanism