Install & Compatibility
Where this runs
tested against v0.19.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.122s · 21.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.120s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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!")
gitlint --version
Debug
Known issues
breakingPython 3.6 is no longer supported. Projects using gitlint must upgrade to Python 3.7 or newer.fixUpgrade your Python environment to 3.7+.
affects: 0.19.0 and later
breakingPython 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).fixUpgrade your Python environment to 3.6+ (preferably 3.7+).
affects: 0.15.0 and later
deprecatedThe 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.fixNo 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`.
affects: 0.19.0 and later
gotchaGitlint 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.fixReview 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.
affects: 0.18.0 (warning introduced), future release (breaking change)
Errors
Common errors & fixes
Usage: gitlint [OPTIONS] COMMAND [ARGS]... Error: No such command '.pre-commit-config.yaml'.
This error, often accompanied by `exit code: 253`, occurs when `pre-commit` is misconfigured and passes its own configuration file or other non-command arguments to `gitlint` as if it were a command itself.
fixEnsure your `.pre-commit-config.yaml` for `gitlint` correctly specifies the hook and places `--msg-filename` at the end of the `args` list if you are passing other custom arguments. A common fix is to explicitly set `entry: gitlint` and ensure `--msg-filename` is the last argument.
An error occurred while executing '/usr/bin/git config --get user.name': b''.
This error means that `gitlint` attempted to retrieve the Git user name or email for a staged commit, but these values (`user.name` or `user.email`) are not set in your local or global Git configuration.
fixSet your Git user name and email using `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"`. If the issue is specific to a repository, use `git config user.name "Your Name"` and `git config user.email "you@example.com"` within that repository.
gitlint: command not found
The `gitlint` executable is not located in the system's PATH or in the specific environment where the Git hook or CI/CD process is attempting to run it.
fixVerify that `gitlint` is installed (e.g., `pip install gitlint`) and that the directory containing its executable is included in your system's PATH. If using `pre-commit`, ensure the hook definition correctly resolves the `gitlint` binary, potentially by specifying `language: python` or ensuring `gitlint` is available in the `pre-commit` environment.
Error: Invalid value for "--msg-filename": Could not open file: --contrib=CT1: No such file or directory.
This issue arises when using `gitlint` with `pre-commit` and custom arguments (like `--contrib`). `pre-commit` might incorrectly interpret a custom argument as the filename for `--msg-filename` if `--msg-filename` is not the last argument in the `args` list.
fixIn your `.pre-commit-config.yaml`, explicitly define the `gitlint` hook and ensure that `--msg-filename` is the very last argument in the `args` array. For example: `args: [--contrib=CT1, --msg-filename]`
Upgrade
Version history
0.19.1latest on PyPI · released Mar 10, 2023
Audit
Dependencies
No dependency data recorded yet.