or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mdcore-api.mdindex.mdvalidation-rules.md
tile.json

index.mddocs/

Commitlint

Commitlint is a comprehensive tool and ecosystem for linting commit messages to ensure they follow conventional commit formats. It provides a modular architecture with CLI tools, configuration presets, parsing engines, and validation rules. The system supports extensible configuration through shared npm packages, integrates with the conventional-changelog ecosystem, and offers multiple configuration options for different project types.

Package Information

  • Package Name: @commitlint/cli
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install -g @commitlint/cli @commitlint/config-conventional

Core Imports

const {load, lint, read, format} = require('@commitlint/core');

For ES modules:

import {load, lint, read, format} from '@commitlint/core';

Individual package imports:

const lint = require('@commitlint/lint');
const load = require('@commitlint/load');
const parse = require('@commitlint/parse');
const format = require('@commitlint/format');

Basic Usage

# Install commitlint CLI and conventional config
npm install -g @commitlint/cli @commitlint/config-conventional

# Add configuration file
echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

# Lint a commit message
echo 'feat: add new feature' | commitlint

# Lint commits in a range
commitlint --from HEAD~1 --to HEAD

# Lint commits from stdin
echo 'fix: correct bug in parser' | commitlint

# Use with git hooks
echo 'npx --no -- commitlint --edit "$1"' > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Architecture

Commitlint is built around several key components:

  • CLI Interface: Command-line tools (@commitlint/cli) for linting commit messages with comprehensive flag support
  • Core Engine: Central API (@commitlint/core) that aggregates loading, linting, parsing, and formatting functionality
  • Configuration System: Extensible configuration loading (@commitlint/load) with preset support and plugin architecture
  • Rule Engine: 35 built-in validation rules (@commitlint/rules) covering all parts of conventional commits
  • Parser Integration: Commit message parsing (@commitlint/parse) using conventional-commits-parser
  • Output Formatting: Customizable report formatting (@commitlint/format) with colored console output
  • Git Integration: Direct git history reading (@commitlint/read) with commit range support
  • Ecosystem Integration: Configuration presets for popular project types (Angular, Lerna, Nx, etc.)

Capabilities

CLI Interface

Command-line interface for linting commit messages with comprehensive options for different use cases including git hooks, CI/CD integration, and interactive usage.

commitlint [input] [options]

# Core options
--config, -g <path>     # Path to config file
--print-config [format] # Print resolved config
--edit, -e [file]       # Read from commit file
--env, -E <variable>    # Read from environment variable
--from, -f <ref>        # Lower commit range  
--to, -t <ref>          # Upper commit range
--format, -o <format>   # Output format
--quiet, -q             # Toggle console output
--verbose, -V           # Enable verbose output
--color, -c             # Toggle colored output
--strict, -s            # Strict mode exit codes

CLI Interface

Core Programming API

Programmatic interface for integrating commitlint into other tools and workflows. Provides functions for configuration loading, commit message linting, and result formatting.

// Configuration loading
function load(seed?: UserConfig, options?: LoadOptions): Promise<QualifiedConfig>;

// Commit message linting  
function lint(message: string, rules?: QualifiedRules, opts?: LintOptions): Promise<LintOutcome>;

// Commit message parsing
function parse(message: string, parser?: Parser, parserOpts?: ParserOptions): Promise<Commit>;

// Result formatting
function format(report?: FormattableReport, options?: FormatOptions): string;

// Git history reading
function read(settings: GetCommitMessageOptions): Promise<string[]>;

Core API

Configuration System

Flexible configuration system supporting multiple formats, shareable presets, and extensible rules. Includes built-in configurations for popular project types and development workflows.

interface UserConfig {
  extends?: string | string[];
  rules?: Partial<RulesConfig>;
  parserPreset?: string | ParserPreset;
  ignores?: ((commit: string) => boolean)[];
  plugins?: (string | Plugin)[];
  formatter?: string;
  helpUrl?: string;
}

Built-in Configuration Presets:

  • @commitlint/config-conventional - Standard conventional commits
  • @commitlint/config-angular - Angular commit convention
  • @commitlint/config-lerna-scopes - Lerna workspace scopes
  • @commitlint/config-nx-scopes - Nx workspace scopes

Configuration

Validation Rules

Comprehensive rule system with 35+ built-in rules covering all aspects of conventional commit messages. Rules are configurable with severity levels and conditions.

// Rule configuration tuple format
type RuleConfigTuple<T> = 
  | Readonly<[RuleConfigSeverity.Disabled]>
  | Readonly<[RuleConfigSeverity, RuleConfigCondition]>
  | Readonly<[RuleConfigSeverity, RuleConfigCondition, T]>

enum RuleConfigSeverity {
  Disabled = 0,
  Warning = 1, 
  Error = 2,
}

type RuleConfigCondition = 'always' | 'never';

Rule Categories:

  • Type rules: type-case, type-empty, type-enum, type-max-length, type-min-length
  • Scope rules: scope-case, scope-empty, scope-enum, scope-max-length, scope-min-length
  • Subject rules: subject-case, subject-empty, subject-full-stop, subject-max-length, subject-min-length
  • Body rules: body-case, body-empty, body-full-stop, body-leading-blank, body-max-length
  • Header rules: header-case, header-full-stop, header-max-length, header-min-length
  • Footer rules: footer-empty, footer-leading-blank, footer-max-length, footer-min-length

Validation Rules

Utility Functions

Helper functions for commit message validation and processing.

// Validation utilities from @commitlint/ensure
function notEmpty(value: string): boolean;
function maxLength(value: string, max: number): boolean; 
function minLength(value: string, min: number): boolean;
function maxLineLength(value: string, max: number): boolean;
function ensureCase(value: string, target: TargetCaseType): boolean;
function ensureEnum(value: string, enumList: string[]): boolean;

// Ignore checking from @commitlint/is-ignored
function isIgnored(commit?: string, opts?: IsIgnoredOptions): boolean;

Common Utilities:

  • @commitlint/ensure - Validation helper functions for custom rules
  • @commitlint/is-ignored - Check if commits should be ignored during linting
  • @commitlint/to-lines - Convert commit messages to line arrays

Types

// Core commit structure
interface Commit {
  raw: string;
  header: string;
  type: string | null;
  scope: string | null;
  subject: string | null;
  body: string | null;
  footer: string | null;
  mentions: string[];
  notes: CommitNote[];
  references: CommitReference[];
  revert: any;
  merge: any;
}

// Linting results
interface LintOutcome {
  valid: boolean;
  errors: LintRuleOutcome[];
  warnings: LintRuleOutcome[];
  input: string;
}

// Rule outcome
interface LintRuleOutcome {
  level: RuleConfigSeverity;
  valid: boolean;
  name: string;
  message: string;
}

// Configuration loading options
interface LoadOptions {
  cwd?: string;
  file?: string;
}

// Linting options
interface LintOptions {
  ignores?: ((commit: string) => boolean)[];
  defaultIgnores?: boolean;
  parserOpts?: ParserOptions;
}

// Commit reading options
interface GetCommitMessageOptions {
  cwd?: string;
  from?: string;
  to?: string;
  edit?: boolean | string;
  gitLogArgs?: string;
}

// Format options
interface FormatOptions {
  color?: boolean;
  signs?: [string, string, string];
  verbose?: boolean;
  helpUrl?: string;
}

// Utility types
type Matcher = (commit: string) => boolean;

interface IsIgnoredOptions {
  ignores?: Matcher[];
  defaults?: boolean;
}