gitlint

Configuration rules are specialized user-defined rules that are applied once per commit BEFORE any other rules are run. They are designed to dynamically modify gitlint's configuration or the commit object itself based on specific circumstances (e.g., modifying behavior for all 'Release' commits).

Warning: Configuration rules can drastically change how gitlint behaves. Before implementing one, check if:

1. gitlint supports your use-case out-of-the-box (e.g., ignore rules).
2. A Contrib Rule already exists.
3. You can achieve your goal using a standard Commit or Line user-defined rule.

To implement a configuration rule, inherit from gitlint.rules.ConfigurationRule and implement the apply(self, config, commit) method.

from gitlint.rules import ConfigurationRule

class MyConfigRule(ConfigurationRule):
    name = "my-rule-name"
    id = "UCR1"

    def apply(self, config, commit):
        # Modify config or commit here
        pass

To create a LineRule, extend the LineRule class.

Requirements:

• name: A human-friendly string.
• id: A unique identifier (it is recommended to start with UL for User-defined Line-rules).
• target: Specifies where the rule is applied. Use CommitMessageTitle to target only the title, or CommitMessageBody to target every line in the body.
• validate(self, line, _commit): A method that receives the current line as the first argument and the commit object as the second.

Configurability: You can define options_spec using classes like ListOption to make your rule configurable. Options are accessed via self.options["option-name"].value.

Example: Enforcing that the commit title does not contain specific special characters.

from gitlint.rules import LineRule, RuleViolation, CommitMessageTitle
from gitlint.options import ListOption

class SpecialChars(LineRule):
    """Enforce that the commit message title does not contain specific characters."""

    name = "title-no-special-chars"
    id = "UL1"
    target = CommitMessageTitle

    options_spec = [
        ListOption(
            "special-chars",
            ["$", "^", "%", "@", "!", "*", "(", ")"],
            "Comma separated list of chars that cannot occur in the title",
        )
    ]

    def validate(self, line, _commit):
        violations = []
        for char in self.options["special-chars"].value:
            if char in line:
                msg = f"Title contains the special character '{char}'"
                violation = RuleViolation(self.id, msg, line)
                violations.append(violation)

        return violations

To create a CommitRule, extend the CommitRule class.

Requirements:

• name: A human-friendly string.
• id: A unique identifier (it is recommended to start with UC for User-defined Commit-rules).
• validate(self, commit): A method that receives a single commit argument. It should return a RuleViolation (or a list of them) if the commit fails validation, or return nothing if it passes.

Example: Checking for a "Signed-off-by" line in the commit body.

from gitlint.rules import CommitRule, RuleViolation

class SignedOffBy(CommitRule):
    """Enforce that each commit contains a "Signed-off-by" line."""

    name = "body-requires-signed-off-by"
    id = "UC2"

    def validate(self, commit):
        for line in commit.message.body:
            if line.startswith("Signed-off-by"):
                return

        msg = "Body does not contain a 'Signed-off-by' line"
        return [RuleViolation(self.id, msg, line_nr=1)]

To signal a violation within a custom rule, the validate(...) method must return a list of RuleViolation objects.

Key requirements for validate(...):

• If there are no violations, you can return an empty list [] or simply skip the return statement.
• If there is a single violation, you must return a list containing that one item (e.g., [RuleViolation(...)]).
• For LineRules, if you do not explicitly set the line_nr, gitlint will attempt to automatically set it to the correct line number.

def validate(self, commit):
    for line_nr, line in commit.message.body:
        if "Jon Snow" in line:
            # Add 1 to the line_nr to offset the title which is on the first line
            violation_line_nr = line_nr + 1
            msg = "Commit message has the words 'Jon Snow' in it"
            return [RuleViolation(self.id, msg, line, violation_line_nr)]
    return []