gitlint

Lint and enforce commit message conventions

TLDR

Lint the most recent commit

$ gitlint

Lint a specific commit

$ gitlint --commit [commit-hash]

Lint a range of commits

$ gitlint --commits [HEAD~5..HEAD]

Lint a message from stdin

$ echo "Fix bug" | gitlint --stdin-msg

Generate a default config file

$ gitlint generate-config

Install as a commit-msg git hook

$ gitlint install-hook

Uninstall the commit-msg hook

$ gitlint uninstall-hook

Lint with a specific config file

$ gitlint --config [.gitlint] --commits [main..HEAD]

gitlint enforces commit message conventions by checking that messages follow configured rules for format, length, and content. This ensures consistent, readable commit history across a project.
Default rules include title max length (72 chars), title not ending with a period, body max line length (80 chars), and a blank line between title and body. Contrib rules add support for Conventional Commits and other formats.
Custom Python rules can be written to enforce project-specific conventions. The tool integrates naturally into CI pipelines by linting commit ranges with --commits.

PARAMETERS

--commit SHA

Check a specific commit.

--commits RANGE

Check a range of commits.

--stdin-msg

Read commit message from stdin instead of git log.

--msg-filename FILE

Read commit message from a file.

-c RULE.OPTION=VALUE

Set a rule option on the command line.

--config FILE

Use a specific config file.

--ignore RULES

Comma-separated list of rules to ignore.

--contrib RULES

Comma-separated list of contrib rules to enable (e.g., contrib-title-conventional-commits).

--debug

Enable debug output.

--help

Display help information.

CONFIGURATION

.gitlint

Project-level configuration file defining commit message rules, ignored rules, and custom settings. Uses INI format with sections for each rule.

COMMANDS

generate-config

Create a default .gitlint configuration file.

install-hook

Install gitlint as a git commit-msg hook.

uninstall-hook

Remove the gitlint commit-msg hook.

CAVEATS

Requires Python 3. When used as a hook, only the latest commit message is checked. The --commits flag is needed for CI to check all commits in a branch. Custom rules require writing Python classes.