or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

built-in-rules.mdcli-interface.mdcommit-reading.mdconfiguration-presets.mdconfiguration-system.mdindex.mdlinting-engine.mdoutput-formatting.md
tile.json

tessl/npm-commitlint--cli

Lint your commit messages with configurable rules and conventional commit support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@commitlint/cli@19.8.x

To install, run

npx @tessl/cli install tessl/npm-commitlint--cli@19.8.0

index.mddocs/

Commitlint

Commitlint is a powerful linting tool for Git commit messages that enforces conventional commit format standards across development teams. It provides both CLI and programmatic APIs for validating commit messages against configurable rules, supporting multiple preset configurations, and integrating seamlessly with Git hooks and CI/CD pipelines.

Package Information

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

Core Imports

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

For CLI usage:

# Install globally
npm install -g @commitlint/cli

# Or use via npx
npx commitlint --help

For individual packages:

import load from "@commitlint/load";
import lint from "@commitlint/lint";
import read from "@commitlint/read";
import format from "@commitlint/format";

Basic Usage

CLI Usage

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

# Lint specific commit range
commitlint --from=HEAD~3 --to=HEAD

# Lint last commit
commitlint --last

# Lint with specific config
commitlint --config ./commitlint.config.js

# Print resolved configuration
commitlint --print-config

Programmatic Usage

import { load, lint } from "@commitlint/core";

// Load configuration
const config = await load({
  extends: ["@commitlint/config-conventional"]
});

// Lint a commit message
const result = await lint(
  "feat: add new authentication system",
  config.rules
);

console.log(result.valid); // true/false
console.log(result.errors); // array of error objects
console.log(result.warnings); // array of warning objects

Architecture

Commitlint follows a modular architecture with independent packages:

  • CLI Interface: Full-featured command-line tool with extensive options (@commitlint/cli)
  • Core API: Main orchestration functions (@commitlint/core)
  • Configuration System: Flexible loading and extension resolution (@commitlint/load)
  • Linting Engine: Rule-based message validation (@commitlint/lint)
  • Message Reading: Git integration for reading commits (@commitlint/read)
  • Output Formatting: Customizable result formatting (@commitlint/format)
  • Rule System: 25+ built-in rules covering all commit parts (@commitlint/rules)
  • Type System: Complete TypeScript definitions (@commitlint/types)
  • Plugin System: Extensible architecture for custom rules
  • Preset System: Pre-built configurations for popular conventions

Capabilities

CLI Interface

Command-line tool for linting commit messages with extensive configuration options, range support, and flexible input methods.

interface CliFlags {
  color: boolean;
  config?: string;
  "print-config"?: "text" | "json" | "";
  cwd: string;
  edit?: string | boolean;
  env?: string;
  extends?: (string | number)[];
  "help-url"?: string;
  from?: string;
  "from-last-tag"?: boolean;
  "git-log-args"?: string;
  last?: boolean;
  format?: string;
  "parser-preset"?: string;
  quiet: boolean;
  to?: string;
  verbose?: boolean;
  strict?: boolean;
}

CLI Interface

Configuration System

Flexible configuration loading with support for extends, plugins, custom rules, and multiple configuration sources.

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

interface LoadOptions {
  cwd?: string;
  file?: string;
}

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

Configuration System

Linting Engine

Core message validation against configurable rules with detailed error reporting and rule outcome tracking.

function lint(
  message: string,
  rawRulesConfig?: QualifiedRules,
  rawOpts?: LintOptions
): Promise<LintOutcome>;

interface LintOptions {
  defaultIgnores?: boolean;
  ignores?: ((commit: string) => boolean)[];
  parserOpts?: Options;
  plugins?: PluginRecords;
  helpUrl?: string;
}

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

Linting Engine

Commit Reading

Git integration for reading commit messages from various sources including history ranges, edit files, and environment variables.

function read(options: GetCommitMessageOptions): Promise<string[]>;

interface GetCommitMessageOptions {
  cwd?: string;
  from?: string;
  fromLastTag?: boolean;
  to?: string;
  last?: boolean;
  edit?: boolean | string;
  gitLogArgs?: string;
}

Commit Reading

Built-in Rules

Comprehensive rule system with 25+ built-in rules covering all parts of conventional commits including type, scope, subject, body, and footer validation.

type Rule<Value = never> = (
  parsed: Commit,
  when?: RuleConfigCondition,
  value?: Value
) => RuleOutcome | Promise<RuleOutcome>;

type RuleConfigCondition = "always" | "never";
type RuleOutcome = Readonly<[boolean, string?]>;

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

Built-in Rules

Configuration Presets

Pre-built rule configurations for popular commit conventions including conventional commits, Angular style, and workspace-specific scoping.

// Conventional commits preset
const conventionalConfig = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [2, "always", [
      "build", "chore", "ci", "docs", "feat", 
      "fix", "perf", "refactor", "revert", "style", "test"
    ]],
    "header-max-length": [2, "always", 100]
  }
};

Configuration Presets

Output Formatting

Customizable result formatting with color support, verbose output, and help URL integration for enhanced developer experience.

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

interface FormatOptions {
  color?: boolean;
  signs?: readonly [string, string, string];
  colors?: readonly [ChalkColor, ChalkColor, ChalkColor];
  verbose?: boolean;
  helpUrl?: string;
}

Output Formatting

Common Type Definitions

interface QualifiedConfig {
  extends: string[];
  formatter: string;
  rules: QualifiedRules;
  parserPreset?: ParserPreset;
  ignores?: ((commit: string) => boolean)[];
  defaultIgnores?: boolean;
  plugins: PluginRecords;
  helpUrl: string;
}

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

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

type TargetCaseType = 
  | "camel-case" | "kebab-case" | "snake-case" | "pascal-case"
  | "start-case" | "upper-case" | "uppercase" | "sentence-case"
  | "sentencecase" | "lower-case" | "lowercase" | "lowerCase";

interface Plugin {
  rules: {
    [ruleName: string]: Rule | AsyncRule | SyncRule;
  };
}

interface UserPromptConfig {
  settings?: {
    scopeEnumSeparator?: string;
    enableMultipleScopes?: boolean;
  };
  messages?: {
    skip?: string;
    max?: string;
    min?: string;
    emptyWarning?: string;
    upperLimitWarning?: string;
    lowerLimitWarning?: string;
    [key: string]: string | undefined;
  };
  questions?: Partial<Record<string, {
    description?: string;
    messages?: { [K: string]: string };
    enum?: {
      [enumName: string]: {
        description?: string;
        title?: string;
        emoji?: string;
      };
    };
  }>>;
}

interface FormattableReport {
  results?: (FormattableResult & WithInput)[];
}

interface FormattableResult {
  errors?: FormattableProblem[];
  warnings?: FormattableProblem[];
}

interface FormattableProblem {
  level: RuleConfigSeverity;
  name: string;
  message: string;
}

interface WithInput {
  input?: string;
}

type ChalkColor = string;