commitlint

Was macht commitlint?

Validiert Commit-Nachrichten anhand des Conventional-Commits-Formats mittels commitlint-Konfiguration und -Regeln.

Wann dieses Skill verwendet werden sollte

Verwenden Sie dieses Skill, wenn:

• Sie commitlint für ein Repository einrichten möchten
• Sie commitlint-Regeln und gemeinsam nutzbare Konfigurationen konfigurieren möchten
• Sie commitlint in Pre-Commit-Hooks oder CI/CD-Pipelines integrieren möchten
• Sie Regeln aus der commitlint-Konfiguration extrahieren möchten, um LLM-Prompts zur Commit-Erzeugung zu generieren
• Sie Commit-Nachrichten programmatisch validieren möchten
• Sie Fehler in der commitlint-Konfiguration oder bei der Validierung beheben möchten
• Sie die Syntax und Schweregrade der commitlint-Regeln verstehen möchten
• Sie commitlint-Konfigurationsdateien in einem Repository erkennen möchten

Kernfähigkeiten

Konfigurationserkennung

Commitlint verwendet cosmiconfig, um Konfigurationsdateien in dieser Prioritätsreihenfolge zu finden:

Dedizierte Konfigurationsdateien:

.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

Paketdateien:

• package.json mit Feld commitlint
• package.yaml (PNPM) mit Feld commitlint

Konfigurationsformate

JavaScript ES Modules (Empfohlen):

// commitlint.config.js oder 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"

Regelkonfiguration

Regeln werden als Arrays konfiguriert: [Schweregrad, Anwendbarkeit, Wert]

Schweregrade:

Stufe	Bedeutung	TypeScript-Enum
0	Deaktiviert	RuleConfigSeverity.Disabled
1	Warnung	RuleConfigSeverity.Warning
2	Fehler	RuleConfigSeverity.Error

Anwendbarkeit:

• 'always' - Regel muss zutreffen
• 'never' - Regel darf nicht zutreffen

Beispielregeln:

rules: {
  // Fehler, wenn der Typ nicht in der Aufzählung ist
  'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']],

  // Fehler, wenn der Typ leer ist
  'type-empty': [2, 'never'],

  // Fehler, wenn der Betreff leer ist
  'subject-empty': [2, 'never'],

  // Fehler, wenn der Header 100 Zeichen überschreitet
  'header-max-length': [2, 'always', 100],

  // Fehler, wenn der Betreff mit einem Punkt endet
  'subject-full-stop': [2, 'never', '.'],

  // Warnung, wenn der Textkörper keine führende Leerzeile hat
  'body-leading-blank': [1, 'always'],
}

Häufige Konfigurationen

@commitlint/config-conventional

Die am weitesten verbreitete gemeinsam nutzbare Konfiguration. Standard-Fehler-Regeln:

Regel	Konfiguration	Bestandenes Beispiel	Fehlgeschlagenes Beispiel
type-enum	['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test']	fix: nachricht	foo: nachricht
type-case	'lowerCase'	fix: nachricht	FIX: nachricht
type-empty	never	fix: nachricht	: nachricht
subject-case	never + ['sentence-case', 'start-case', 'pascal-case', 'upper-case']	fix: eine nachricht	fix: Eine Nachricht
subject-empty	never	fix: nachricht	fix:
subject-full-stop	never, '.'	fix: nachricht	fix: nachricht.
header-max-length	100	Kurzer Header	Header > 100 Zeichen
body-leading-blank	always (Warnung)	Leerzeile vor Textkörper	Keine Leerzeile
body-max-line-length	100	Zeilen <= 100 Zeichen	Zeile > 100 Zeichen
footer-leading-blank	always (Warnung)	Leerzeile vor Fußzeile	Keine Leerzeile
footer-max-line-length	100	Zeilen <= 100 Zeichen	Zeile > 100 Zeichen

Vollständiges Konfigurationsschema

// commitlint.config.js
export default {
  // Gemeinsam nutzbare Konfigurationen erweitern (aufgelöst über node-Auflösung)
  extends: ['@commitlint/config-conventional'],

  // Parser-Voreinstellung zum Parsen von Commit-Nachrichten
  parserPreset: 'conventional-changelog-atom',

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

  // Benutzerdefinierte Regeln (überschreiben geerbte Regeln)
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
  },

  // Funktionen, die true zurückgeben, um bestimmte Commits zu ignorieren
  // Mit Standard-Ignores zusammengeführt (Merge-Commits, Reverts, Semver-Tags)
  ignores: [(commit) => commit.includes('WIP')],

  // Ob Standard-Ignore-Muster verwendet werden sollen
  // Standardmuster: 'Merge pull request', 'Revert X', 'v1.2.3', usw.
  defaultIgnores: true,

  // Benutzerdefinierte Hilfe-URL bei Fehlschlag
  helpUrl: 'https://example.com/commit-guidelines',

  // Prompt-Konfiguration (für @commitlint/cz-commitlint)
  prompt: {
    messages: {},
    questions: {
      type: {
        description: 'Wählen Sie die Art der Änderung:',
      },
    },
  },
};

CLI-Nutzung

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

Häufige Befehle

# Letzten Commit prüfen
npx commitlint --last

# Einen Bereich von Commits prüfen
npx commitlint --from HEAD~5

# Ab einem bestimmten Commit prüfen
npx commitlint --from abc1234

# Nachricht von stdin prüfen
echo "feat: funktion hinzufügen" | npx commitlint

# Nachricht aus Datei prüfen
npx commitlint < .git/COMMIT_EDITMSG

# Mit edit-Flag prüfen (liest .git/COMMIT_EDITMSG)
npx commitlint --edit

# Mit benutzerdefiniertem Konfigurationspfad prüfen
npx commitlint --config ./custom-commitlint.config.js

# Aufgelöste Konfiguration ausgeben
npx commitlint --print-config

# Strikter Modus (Warnungen werden zu Exit-Code 2)
npx commitlint --last --strict

Exit-Codes

Code	Bedeutung
0	Erfolg (keine Fehler)
1	Lint-Fehler gefunden
2	Warnungen gefunden (nur strikter Modus)
3	Fehler gefunden (strikter Modus)
9	Konfigurationsdatei fehlt (mit -g-Flag)

Regelreferenz

Typ-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
type-enum	type ist im Wert enthalten	always
type-case	type ist in Groß-/Kleinschreibung value	always, 'lower-case'
type-empty	type ist leer	never
type-max-length	type hat value oder weniger Zeichen	always, Infinity
type-min-length	type hat value oder mehr Zeichen	always, 0

Betreff-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
subject-case	subject ist in Groß-/Kleinschreibung value	always
subject-empty	subject ist leer	never
subject-full-stop	subject endet mit value	never, '.'
subject-max-length	subject hat value oder weniger Zeichen	always, Infinity
subject-min-length	subject hat value oder mehr Zeichen	always, 0
subject-exclamation-mark	subject hat Ausrufezeichen vor :	never

Bereichs-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
scope-enum	scope ist im Wert enthalten	always, []
scope-case	scope ist in Groß-/Kleinschreibung value	always, 'lower-case'
scope-empty	scope ist leer	never
scope-max-length	scope hat value oder weniger Zeichen	always, Infinity
scope-min-length	scope hat value oder mehr Zeichen	always, 0

Header-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
header-case	header ist in Groß-/Kleinschreibung value	always, 'lower-case'
header-full-stop	header endet mit value	never, '.'
header-max-length	header hat value oder weniger Zeichen	always, 72
header-min-length	header hat value oder mehr Zeichen	always, 0
header-trim	header hat keine führenden/abschließenden Leerzeichen	always

Textkörper-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
body-leading-blank	body beginnt mit leerer Zeile	always
body-empty	body ist leer	never
body-max-length	body hat value oder weniger Zeichen	always, Infinity
body-max-line-length	Zeilen von body haben value oder weniger Zeichen (URLs ausgeschlossen)	always, Infinity
body-min-length	body hat value oder mehr Zeichen	always, 0
body-case	body ist in Groß-/Kleinschreibung value	always, 'lower-case'
body-full-stop	body endet mit value	never, '.'

Fußzeilen-Regeln

Regel	Bedingung	Standard-Anwendbarkeit
footer-leading-blank	footer beginnt mit leerer Zeile	always
footer-empty	footer ist leer	never
footer-max-length	footer hat value oder weniger Zeichen	always, Infinity
footer-max-line-length	Zeilen von footer haben value oder weniger Zeichen	always, Infinity
footer-min-length	footer hat value oder mehr Zeichen	always, 0

Groß-/Kleinschreibungs-Werte

Für Regeln, die die Groß-/Kleinschreibung prüfen (*-case):

[
  'lower-case',    // kleinschreibung
  'upper-case',    // GROSSSCHREIBUNG
  'camel-case',    // camelCase
  'kebab-case',    // kebab-case
  'pascal-case',   // PascalCase
  'sentence-case', // Satzschreibung
  'snake-case',    // snake_case
  'start-case',    // Start Case
]

Programmatische Nutzung

Konfiguration laden

import load from '@commitlint/load';

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

Nachricht validieren

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

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

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

LLM-Integrationsmuster

Regeln für die Prompt-Erzeugung extrahieren

LLM-freundliche Einschränkungen aus der commitlint-Konfiguration erzeugen:

def extract_rules_for_prompt(config: dict) -> str:
    """Extrahiert commitlint-Regeln in ein LLM-freundliches Format."""
    rules = config.get("rules", {})
    prompt_parts = []

    # type-enum extrahieren, falls vorhanden
    if "type-enum" in rules:
        level, applicability, types = rules["type-enum"]
        if level > 0 and applicability == "always":
            prompt_parts.append(f"Erlaubte Commit-Typen: {', '.join(types)}")

    # scope-enum extrahieren, falls vorhanden
    if "scope-enum" in rules:
        level, applicability, scopes = rules["scope-enum"]
        if level > 0 and applicability == "always":
            prompt_parts.append(f"Erlaubte Bereiche: {', '.join(scopes)}")

    # header-max-length extrahieren, falls vorhanden
    if "header-max-length" in rules:
        level, applicability, max_len = rules["header-max-length"]
        if level > 0:
            prompt_parts.append(f"Maximale Header-Länge: {max_len} Zeichen")

    # subject-case extrahieren, falls vorhanden
    if "subject-case" in rules:
        level, applicability, case = rules["subject-case"]
        if level > 0 and applicability == "always":
            prompt_parts.append(f"Groß-/Kleinschreibung des Betreffs: {case}")

    return "\n".join(prompt_parts)

Commit-Vorlage erzeugen

function generateLlmPrompt(config) {
  const rules = config.rules || {};

  let prompt = `Generieren Sie eine gültige Git-Commit-Nachricht im Conventional-Commits-Format.\n`;
  prompt += `Format: <typ>(<bereich>): <betreff>\n\n<textkörper>\n\n<fußzeile>\n\n`;
  prompt += `Regeln:\n`;

  if (rules['type-enum']) {
    prompt += `- Typ muss einer der folgenden sein: ${rules['type-enum'][2].join(', ')}\n`;
  }

  if (rules['header-max-length']) {
    prompt += `- Header darf maximal ${rules['header-max-length'][2]} Zeichen lang sein\n`;
  }

  if (rules['subject-case']) {
    prompt += `- Betreff muss in ${rules['subject-case'][2]}-Schreibweise sein\n`;
  }

  return prompt;
}

Konfiguration aus Repository erkennen

def detect_commitlint_config(repo_path: str) -> Optional[dict]:
    """Erkennt und lädt commitlint-Konfiguration aus einem Repository."""
    import os
    import json

    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",
    ]

    for file in config_files:
        path = os.path.join(repo_path, file)
        if os.path.exists(path):
            with open(path) as f:
                if file.endswith(".json"):
                    return json.load(f)
                # Bei JS/TS-Dateien könnte eine komplexere Implementierung erforderlich sein
                return {"file": file}

    # In package.json suchen
    package_path = os.path.join(repo_path, "package.json")
    if os.path.exists(package_path):
        with open(package_path) as f:
            package = json.load(f)
            if "commitlint" in package:
                return package["commitlint"]

    return None

Fehlerbehebung

Häufige Probleme

Problem: „Configuration file not found“

• Stellen Sie sicher, dass die Konfigurationsdatei vorhanden ist
• Überprüfen Sie die Schreibweise der Dateinamen, die in cosmiconfig unterstützt werden
• Bei globaler Installation verwenden Sie das --config-Flag oder -g

Problem: Regeln werden nicht angewendet

• Überprüfen Sie die Regel-Schreibweise (z. B. type-enum vs. type_enum)
• Stellen Sie sicher, dass der Schweregrad größer als 0 ist
• Stellen Sie sicher, dass die Anwendbarkeit korrekt ist ('always' vs. 'never')
• Überprüfen Sie, ob erweiterte Konfigurationen (extends) Regeln überschreiben

Problem: CI schlägt mit Exit-Code 1 fehl

• Prüfen Sie den letzten Commit auf Formatierungsprobleme vor dem Pushen
• Verwenden Sie commitlint --last, um den letzten Commit lokal zu prüfen
• Erwägen Sie die Verwendung von Husky mit commitlint als Pre-Commit-Hook
• Wenn Warnungen toleriert werden sollen, deaktivieren Sie Warnungsregeln oder setzen Sie sie auf Schweregrad 0

Problem: TypeScript-Konfiguration wird nicht geladen

• Installieren Sie ts-node oder tsx für die TypeScript-Ausführung
• Konfiguration auf JavaScript umstellen oder als Fallback eine JSON-Datei hinzufügen
• Überprüfen Sie die tsconfig.json auf korrekte Modulauflösungseinstellungen

Debugging-Modus

# Detaillierte Ausgabe aktivieren
npx commitlint --last --verbose

# Aufgelöste Konfiguration prüfen
npx commitlint --print-config

# Einen bestimmten Commit mit einem bestimmten Format prüfen
echo "fix: korrektur" | npx commitlint

# Parsing-Fehler debuggen
npx commitlint --last --help

Hilfreiche Ressourcen

• Offizielle commitlint-Dokumentation: https://commitlint.js.org
• Conventional Commits: https://www.conventionalcommits.org
• Konfigurationsbeispiele: @commitlint/config-conventional README

Kompatibilität

• Node.js >= 18 (für commitlint 19.x)
• Node.js >= 14 (für commitlint 18.x)
• Unterstützt TypeScript, ESM und CommonJS (CJS)
• Funktionen als Pre-Commit-Hook (Husky, lefthook) oder CI-Integration (GitHub Actions, GitLab CI, CircleCI)