Conventional Commits Validator

A lightweight Rust library and CLI tool for validating Git commit messages according to the Conventional Commits specification.

Features

• ✅ Validates commit messages against Conventional Commits v1.0.0
• 🔧 Configurable validation rules
• 📚 Can be used as a library or CLI tool
• 🚀 Lightweight with minimal dependencies
• 🎯 Supports all standard commit types
• 🔍 Detects breaking changes
• 📖 Provides helpful error messages and examples

Installation

From crates.io

cargo install conventional-commits

From source

git clone https://codeberg.org/slundi/conventional-commits
cd conventional-commits
cargo build --release

CLI Usage

Basic validation

# Validate a commit message
commit-check --message "feat: add user authentication"

# Read from stdin
echo "fix: resolve login issue" | commit-check

# Validate with verbose output
commit-check --message "feat(auth): add OAuth support" --verbose

Commands

# Show examples of valid commits
commit-check examples

# Show available commit types
commit-check types

# Validate with custom configuration
commit-check --message "feat: new feature" --max-length 50 --allow-custom-types=false

Configuration Options

Flag	Default	Description
--max-length <N>	72	Maximum description length
--min-length <N>	0	Minimum description length
--allow-custom-types <BOOL>	true	Allow custom commit types
--enforce-lowercase <BOOL>	true	Enforce lowercase first letter in description
--disallow-period <BOOL>	true	Disallow period at end of description
--scopes <SCOPES>	—	Comma-separated list of allowed scopes
--enforce-lowercase-scope <BOOL>	false	Reject scopes with uppercase letters
--require-scope <BOOL>	false	Require a scope on every commit
--issue-pattern <PATTERN>	—	Regex that at least one footer must match
--fix	—	Auto-correct common header mistakes and print the result
--format <text|json>	text	Output format
--verbose	—	Detailed output

Body Cleaning

Automated tools (AI assistants, CI bots) often append trailers like Co-authored-by: or Signed-off-by: to commit bodies. Use clean rules to strip these lines before validation:

# Remove lines by prefix
commit-check --message "$(cat .git/COMMIT_EDITMSG)" \
  --clean-starts-with "Co-authored-by" \
  --clean-starts-with "Signed-off-by"

# Remove lines by regex (can be combined with starts-with rules)
commit-check --message "$(cat .git/COMMIT_EDITMSG)" \
  --clean-regex "^🤖.*"

# Both flags are repeatable and additive with rules from .commit-check.toml

Cleaning also collapses consecutive blank lines and trims trailing whitespace. Each removed line is printed as Removed: <line> so you can see what was stripped.

Integration

See Integration.

Conventional Commits Format

The Conventional Commits specification defines the following format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Standard Types

• feat - A new feature
• fix - A bug fix
• docs - Documentation only changes
• style - Changes that do not affect the meaning of the code
• refactor - A code change that neither fixes a bug nor adds a feature
• perf - A code change that improves performance
• test - Adding missing tests or correcting existing tests
• build - Changes to the build process or auxiliary tools
• ci - Changes to CI configuration files and scripts
• chore - Other changes that don't modify src or test files
• revert - Reverts a previous commit

Examples

feat: add email notifications
fix(auth): resolve token expiration issue
feat!: remove deprecated API endpoints
docs(readme): update installation instructions

feat: add user profiles

Allow users to create and customize their profiles
with avatar upload and bio sections.

Closes #123
BREAKING CHANGE: User model schema has changed

Git Hooks Integration

You can integrate this tool with Git hooks to automatically validate commit messages:

commit-msg hook

Create .git/hooks/commit-msg:

#!/bin/sh
commit-check --message "$(cat "$1")"

Make it executable:

chmod +x .git/hooks/commit-msg

Pre-commit integration

Add to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: conventional-commits
        name: Conventional Commits
        entry: commit-check
        language: system
        stages: [commit-msg]
        args: ["--message"]

API Reference

Core Functions

• validate_commit(message: &str) - Validates a commit message with default configuration
• validate_commit_with_config(message: &str, config: &ValidationConfig) - Validates with custom configuration
• fix_commit_message(message: &str) - Auto-corrects common header mistakes
• clean_commit_body(message, starts_with_rules, regex_rules) - Strips unwanted body lines, collapses blank lines, trims trailing whitespace; returns CleanResult

Types

• ConventionalCommit - Represents a parsed commit
• CommitType - Enum of commit types
• ValidationConfig - Configuration for validation rules
• CommitValidationError - Error types for validation failures
• CleanResult - Result of clean_commit_body: cleaned_message + removed_lines

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development

See Development

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Conventional Commits specification
• commitlint for inspiration
• commitizen for reference implementation

🤝 Contributing

The conventionnal commits checker is developed on Codeberg and mirrored to GitHub.

• Primary Repo: Codeberg main repo
• Mirror: GitHub repo