Getting Started

Installation

From Source

git clone https://github.com/quinnjr/cargo-commitlint.git
cd cargo-commitlint
cargo install --path .

From Crates.io

cargo install cargo-commitlint

Install Git Hooks

After installation, cargo commitlint is available as a cargo subcommand and can install its own git hook.

Built-in Installer

Install the commit-msg hook into the current repository:

cargo commitlint install

Pass --force to replace a hook that is already there, and cargo commitlint uninstall to remove it.

As a dev-dependency

Add it to your Cargo.toml and the build script installs the hook for you:

[dev-dependencies]
cargo-commitlint = "2"

[package.metadata.commitlint]
user-hooks = true

user-hooks = true writes the hook to .commitlint/hooks/ so it can be committed and shared. Point git at it once with git config core.hooksPath .commitlint/hooks. Set no-install = true to disable automatic installation, or COMMITLINT_SKIP=1 to bypass the hook for one commit.

Hook Behavior Without a Binary

The commit-msg hook only validates once a cargo-commitlint binary exists. The installed hook looks for the binary (in target/release/, target/debug/, then on your PATH). If none is found, the hook prints a warning to stderr and exits successfully, so the commit is accepted without any validation.

On a fresh clone, build or install it once so the gate is actually active:

# from the project root
cargo build --release

# or install it globally
cargo install cargo-commitlint

Basic Usage

Validate Commit Messages

# Validate from command line
cargo commitlint check --message "feat: add new feature"

# Validate from stdin
echo "feat: add new feature" | cargo commitlint check

Configuration

Create a commitlint.toml file in your project root:

[rules]
[rules.type]
enum = ["feat", "fix", "docs", "style", "refactor", "test", "chore"]
case = "lowercase"

[rules.scope]
enum = []
case = "lowercase"

subject_case = ["sentence-case"]
header_max_length = 72

Next Steps