Gitlint

0.19.1 · active · verified Sun Apr 12

Gitlint is a highly configurable Python library and command-line tool designed to lint Git commit messages for style and compliance with established conventions (e.g., Conventional Commits). It helps enforce consistent commit history quality within development teams. The current version is 0.19.1, and it typically sees several releases per year, addressing bug fixes, new features, and Python version compatibility.

Warnings

breaking Python 3.6 is no longer supported. Projects using gitlint must upgrade to Python 3.7 or newer.
Fix: Upgrade your Python environment to 3.7+.
breaking Python 2.7 and Python 3.5 are no longer supported. Ensure your environment is using Python 3.6 or newer (though 3.7+ is recommended for latest versions).
Fix: Upgrade your Python environment to 3.6+ (preferably 3.7+).
deprecated The internal use of the `sh` library (for executing git commands) is being deprecated. Version 0.19.0 is the last release to officially support it via `GITLINT_USE_SH_LIB=1`. Future versions may remove this dependency entirely.
Fix: No immediate user action is required unless you explicitly relied on the `sh` library integration. Be aware that future versions might remove `GITLINT_USE_SH_LIB`.
gotcha Gitlint will be switching to `re.search` semantics instead of `re.match` for all rule regexes in a future release. This will change how regexes are matched (matching anywhere in the string vs. only at the beginning). Gitlint will print a warning if your current regexes might be affected.
Fix: Review your custom rule regexes and update them to be compatible with `re.search` semantics if you receive warnings. More details are available in the gitlint documentation.

Install

pip install gitlint Install gitlint

Imports

GitLinter
```
from gitlint.lint import GitLinter
```
Main class for linting operations.
GitContext
```
from gitlint.git import GitContext
```
Represents the Git repository context or a specific commit message.
GitlintOptions
```
from gitlint.options import GitlintOptions
```
Class for configuring gitlint's behavior programmatically.

Quickstart

This quickstart demonstrates how to use `gitlint` programmatically to lint a commit message string. It initializes a `GitlintOptions` object for configuration, creates a `GitContext` from a provided message, and then uses `GitLinter` to find any violations. For typical CLI usage, simply running `gitlint` in a Git repository will lint the latest commit.

import os
from gitlint.lint import GitLinter
from gitlint.git import GitContext
from gitlint.options import GitlintOptions

# Example commit message to lint
commit_message = """feat: Add user authentication

This commit introduces user authentication functionality using OAuth2.0.
It includes new models for users and sessions, and updates the API routes.
"""

# Initialize options (optional, can be customized programmatically)
options = GitlintOptions()
# Example: Disable a specific rule (e.g., body-max-line-length for a longer line)
# options.disabled_rules = ["body-max-line-length"]

# Create a GitContext from the commit message string
# For real-world use in a git repository, you'd typically use:
# GitContext.from_prev_commit() or GitContext.from_staged_commit()
gitcontext = GitContext.from_commit_msg(commit_message)

# Initialize the linter with the options
linter = GitLinter(options)

# Lint the commit message
violations = linter.lint(gitcontext)

# Print any detected violations
if violations:
    print(f"Commit message has {len(violations)} violation(s):")
    for violation in violations:
        print(f"  - [{violation.rule_id}] {violation.message} (Line {violation.line_nr}, Col {violation.violating_line_idx})")
else:
    print("Commit message is clean and adheres to rules!")

view raw JSON →