jamie-bitflight/commitlint

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)