Gitlint Core

Warnings

• breaking Python 3.6 is no longer supported since v0.19.0. Ensure your environment uses Python 3.7 or newer. Earlier versions (2.7 and 3.5) were dropped in v0.15.0.
  Fix: Upgrade your Python interpreter to 3.7 or later. Check the official Python EOL dates for guidance.
• deprecated The `sh` library, used under-the-hood for git command execution, is no longer used by default since v0.18.0. It was completely removed in v0.19.0 (though v0.19.0 stated it was the last release to *support* re-enabling it). Relying on the `GITLINT_USE_SH_LIB=1` environment variable is no longer supported.
  Fix: Remove any reliance on the `GITLINT_USE_SH_LIB` environment variable. The library now uses a more robust internal git command execution.
• gotcha Gitlint switched to `re.search` semantics instead of `re.match` for all rules. This means regexes that previously matched only at the start of a string might now match anywhere. Gitlint will print a warning if your rule regexes might need updating.
  Fix: Review your custom rule regexes and update them if they were implicitly relying on `re.match`'s start-of-string anchoring. Explicitly use `^` for start-of-string matching if needed.
• gotcha Gitlint split into two packages (`gitlint` and `gitlint-core`) in v0.17.0. `gitlint-core` provides the core linting logic with looser dependency requirements, while `gitlint` is the CLI tool with pinned dependencies. Ensure you install the correct package for your use case.
  Fix: For CLI usage or pinned dependencies, `pip install gitlint`. For programmatic use with looser dependency control, `pip install gitlint-core`. If you previously installed `gitlint`, you might need to uninstall both to fully clean up (e.g., `pip uninstall gitlint gitlint-core`).
• gotcha The `commit-msg` git hook was rewritten in Python (around v0.15.0). Existing users of the hook need to reinstall it to benefit from fixes and new features.
  Fix: Run `gitlint uninstall-hook` followed by `gitlint install-hook` in your repository to update the hook.

Install

• pip install gitlint-core Install core library with looser dependencies
• pip install gitlint Install CLI tool (includes gitlint-core with pinned dependencies)

Imports

• Gitlint

  from gitlint.gitlint import Gitlint

• GitlintConfig

  from gitlint.options import GitlintConfig

• CommitRule

  from gitlint.rules import CommitRule

  For creating custom commit rules

Quickstart

Demonstrates how to programmatically lint a commit message string using `gitlint-core`. It initializes a `GitlintConfig` and `Gitlint` instance, then passes a commit message string to the `lint` method. Violations are returned as a list of `RuleViolation` objects.

from gitlint.gitlint import Gitlint
from gitlint.options import GitlintConfig
from gitlint.display import Display

commit_message = (
    "feat: Add new feature\n\n"  # Title
    "This commit introduces a brand new feature to the application.\n\n"
    "It includes several improvements and bug fixes related to the new functionality."
)

# Initialize GitlintConfig (can be customized, or defaults are used)
config = GitlintConfig()
# You can set options programmatically, e.g., config.max_line_length = 100

# Initialize Gitlint with a display (e.g., to print to stdout)
display = Display(config)
gitlint = Gitlint(config, display)

# Lint the commit message
violations = gitlint.lint(commit_msg_str=commit_message)

if violations:
    print(f"Found {len(violations)} violations:")
    for violation in violations:
        print(f"- {violation.rule_id}: {violation.message} (line {violation.line_nr})")
else:
    print("Commit message is valid!")