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, activate the pre-commit skill:

Skill(skill: "python3-development:pre-commit")

Conventional Commits Reference

For Conventional Commits format specification and examples, activate the conventional-commits skill:

Skill(skill: "conventional-commits:conventional-commits")

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

Source Attribution

This skill was created from reference documentation at the commit-polish repository (2025-12-01)