Commit Message Linter

这是一款纯Python开发的Git提交消息校验工具，核心是验证消息是否符合约定式提交规范，支持自定义类型/范围、长度限制、正则匹配等规则。适用于提交前hook校验、CI流水线验证、提交历史质量检查等场景。支持多输入方式，输出含文本、JSON、Markdown三种格式，可生成配置文件，设严格模式将警告转为错误。

charlie-morrison

热度 48.60

最近更新 2026-05-11 17:42:01

分类：开发依赖：代码执行 / 读写文件应用场景：DevOps / 自动化脚本

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add commit-message-linter

Metadata

name: commit-message-linter
description: Validate git commit messages against Conventional Commits spec and configurable rules. Use when linting commit messages, enforcing commit conventions, checking commit history quality, setting up commit-msg hooks, or validating messages in CI pipelines. Supports custom type/scope whitelists, length limits, pattern matching, and multiple output formats (text, JSON, markdown).

Commit Message Linter

Validate commit messages against Conventional Commits and custom rules. Pure Python, no dependencies.

Quick Start

# Lint last commit
python3 scripts/lint_commits.py

# Lint last 5 commits
python3 scripts/lint_commits.py --range HEAD~5..HEAD

# Lint a branch
python3 scripts/lint_commits.py --range main..feature-branch

# Lint a single message
python3 scripts/lint_commits.py --message "feat: add login"

# Read from stdin (git commit-msg hook)
python3 scripts/lint_commits.py --stdin < .git/COMMIT_MSG

# Read from file
python3 scripts/lint_commits.py --file .git/COMMIT_MSG

Output Formats

python3 scripts/lint_commits.py --format text      # human-readable (default)
python3 scripts/lint_commits.py --format json       # CI/tooling
python3 scripts/lint_commits.py --format markdown   # reports

Configuration

Generate default config:

python3 scripts/lint_commits.py init

Creates .commitlintrc.json. Also auto-discovers .commitlintrc or commitlint.config.json.

Key config options:

header_max_length (72) — max header chars
require_conventional (true) — enforce <type>[scope]: <desc> format
types — allowed types (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)
scopes — allowed scopes (empty = any)
require_scope (false) — mandate scope
require_body (false) — mandate body
header_case — description start case: lower/upper/sentence/any
no_trailing_period (true) — reject trailing period on header
forbidden_patterns — regex patterns that reject commits
required_patterns — regex patterns that must match
--strict flag treats warnings as errors

Rules Reference

Rule	Level	Description
header-empty	error	Empty header
header-max-length	error	Header exceeds max length
header-min-length	warning	Header below min length
conventional-format	error	Not Conventional Commits format
type-enum	error	Type not in allowed list
scope-required	error	Missing required scope
scope-enum	error	Scope not in allowed list
description-empty	error	Empty description
description-case	warning	Wrong description case
header-no-period	warning	Trailing period
header-leading-whitespace	error	Leading whitespace
header-trailing-whitespace	warning	Trailing whitespace
body-separator	error	No blank line before body
body-required	warning	Missing required body
body-line-length	warning	Body line too long
body-max-lines	warning	Too many body lines
breaking-change-description	warning	Breaking ! without BREAKING CHANGE: in body
forbidden-pattern	error	Matches forbidden regex
required-pattern	warning	Doesn't match required regex

Exit Codes

0 — all commits pass (warnings OK unless --strict)
1 — errors found (or warnings with --strict)
2 — git/system error

CI Integration (Git Hook)

As commit-msg hook (.git/hooks/commit-msg):

#!/bin/sh
python3 path/to/lint_commits.py --file "$1" --strict

Auto-ignored: merge commits, reverts, version tags, "Initial commit".