### Install Gitlint with Pip

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint using pip for standard installation with pinned dependencies. This is the recommended method.

```sh
pip install gitlint
```

--------------------------------

### Test Gitlint Release Installation

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

This script sets up a clean virtual environment, installs the gitlint package, and performs basic manual tests to verify the installation and functionality.

```sh
# Set release variable for the next steps
export RELEASE_VERSION=`python -c "import gitlint; print(gitlint.__version__)"`; export GITLINT_DIR=`pwd`; export GITLINT_TEST_DIR="/tmp/release-$RELEASE_VERSION"
echo -e "RELEASE_VERSION: $RELEASE_VERSION\nGITLINT_DIR: $GITLINT_DIR\nGITLINT_TEST_DIR: $GITLINT_TEST_DIR"

deactivate # deactivate current virtualenv

# Create virtualenv to test the release
mkdir $GITLINT_TEST_DIR && cd $GITLINT_TEST_DIR
virtualenv -p /usr/bin/python3.8 .venv38 && source .venv38/bin/activate

# Install
gitlint # should not work
pip install --no-cache-dir gitlint # no-cache-dir to disable caching (otherwise pip doesn't always find the new package)

# Do some basic manual testing
cd $GITLINT_TEST_DIR
gitlint --version # should print the correct version
rm -rf foo && git init foo && cd foo
git config user.email foo@bar.com && git config user.name "John Doe"

git commit --allow-empty -m "WIP: föo"
gitlint
# Expected:
# 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: föo"
# 3: B6 Body message is missing

gitlint --debug
# Check version at the top, python version

echo "WIP: föo2" | gitlint
# Expected:
# 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: föo2"
# 3: B6 Body message is missing

echo "föo3" | gitlint -c title-max-length.line-length=2
# Expected:
# 1: T1 Title exceeds max length (4>2): "föo3"
# 1: T8 Title is too short (4<5): "föo3"
# 3: B6 Body message is missing

gitlint install-hook
git commit --allow-empty -m "WIP: föo4"

# Run integration tests
pip install -r $GITLINT_DIR/qa/requirements.txt
pushd $GITLINT_DIR && ./run_tests.sh -i && popd

# Cleanup
deactivate; cd $GITLINT_DIR && rm -rf $GITLINT_TEST_DIR
```

--------------------------------

### Test Package Installation and Basic Functionality

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

This script sets up a temporary directory, creates a virtual environment, installs gitlint from test.pypi.org, and performs basic version checks and commit message linting tests.

```shell
# Set release variable for the next steps
export RELEASE_VERSION=`python -c "import gitlint; print(gitlint.__version__)"`; export GITLINT_DIR=`pwd`; export GITLINT_TEST_DIR="/tmp/release-test-$RELEASE_VERSION"
echo -e "RELEASE_VERSION: $RELEASE_VERSION\nGITLINT_DIR: $GITLINT_DIR\nGITLINT_TEST_DIR: $GITLINT_TEST_DIR"

deactivate # deactivate current virtualenv

# Create virtualenv to test the release
mkdir $GITLINT_TEST_DIR && cd $GITLINT_TEST_DIR
# Python 3.8:
virtualenv -p /usr/bin/python3.8 .venv38 && source .venv38/bin/activate

# Install (make sure the virtualenv of the new release is active)
gitlint # should not work
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple gitlint
pip freeze 

# Do some basic manual testing
cd $GITLINT_TEST_DIR
gitlint --version # should print the correct version
rm -rf foo && git init foo && cd foo
git config user.email foo@bar.com && git config user.name "John Doe"
git commit --allow-empty -m "WIP: föo"
gitlint
# Expected:
# 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: föo"
# 3: B6 Body message is missing

gitlint --debug
# Check version at the top, python version

echo "WIP: föo2" | gitlint
# Expected:
# 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: föo2"
# 3: B6 Body message is missing


echo "föo3" | gitlint -c title-max-length.line-length=2
# Expected:
# 1: T1 Title exceeds max length (4>2): "föo3"
# 1: T8 Title is too short (4<5): "föo3"
# 3: B6 Body message is missing


gitlint install-hook
git commit --allow-empty -m "WIP: föo4"

# Run integration tests
pip install -r $GITLINT_DIR/qa/requirements.txt
pushd $GITLINT_DIR && ./run_tests.sh -i && popd

# Cleanup
deactivate; cd $GITLINT_DIR && rm -rf $GITLINT_TEST_DIR
```

--------------------------------

### Install Gitlint from TestPyPI

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Install the specified gitlint version from the test PyPI repository, with a fallback to the main PyPI.

```sh
pip install --no-cache -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple gitlint==$GITLINT_RELEASE_VERSION
```

--------------------------------

### Install Gitlint-Core from Git Archive URL

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/contributing/releases.md

Install gitlint-core directly from a GitHub source Git archive URL using a specific commit hash. This method supports installing unmerged commits (pending PRs).

```sh
# Set commit hash to install
export COMMIT_HASH="345414171baea56c5b2b8290f17a2a13a685274c"

# Install using pinned dependencies
pip install "gitlint-core [trusted-deps] @ https://github.com/jorisroovers/gitlint/archive/$COMMIT_HASH.tar.gz#subdirectory=gitlint-core"

# Install using looser dependencies
pip install "https://github.com/jorisroovers/gitlint/archive/$COMMIT_HASH.tar.gz#subdirectory=gitlint-core"
```

--------------------------------

### Install Gitlint with Apt-get

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint on Ubuntu or Debian-based systems using the apt-get package manager.

```sh
apt-get install gitlint
```

--------------------------------

### Install Gitlint with Brew

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint on macOS using the Homebrew package manager.

```sh
brew install gitlint
```

--------------------------------

### Run Integration Tests with Installed Gitlint

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Remove the qa environment, attempt integration tests (expected to fail without gitlint), install gitlint from test PyPI, and then run integration tests again.

```sh
hatch env remove qa
hatch run qa:integration-tests # This must fail since no gitlint installed
hatch run qa:pip install --no-cache -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple gitlint==$GITLINT_RELEASE_VERSION
hatch run qa:integration-tests
```

--------------------------------

### Configure Rule Option via .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/options.md

Example of configuring a rule option using a `.gitlint` configuration file.

```ini
[body-max-line-count]
max-line-count=1
```

--------------------------------

### Install Gitlint-core with Pip

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install only the gitlint-core package with pip to use looser dependency requirements.

```sh
pip install gitlint-core
```

--------------------------------

### Install Gitlint from GitHub Source (Looser Dependencies)

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint from a GitHub source archive URL using pip, with looser dependency requirements. Ensure the GITLINT_VERSION environment variable is set.

```sh
# Set version to install
export GITLINT_VERSION="v0.20.0"

# Install using looser dependencies
pip install "https://github.com/jorisroovers/gitlint/archive/$GITLINT_VERSION.tar.gz#subdirectory=gitlint-core"
```

--------------------------------

### Install Gitlint with MacPorts

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint on macOS using the MacPorts package manager.

```sh
port install gitlint
```

--------------------------------

### Install Gitlint and Test with a Bad Commit Message

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/index.md

This snippet shows how to install gitlint using pip and then create a bad commit message to test gitlint's output. It demonstrates the typical workflow for using gitlint.

```bash
pip install gitlint

# Add a bad commit message
git commit --allow-empty  -m " WIP: My bad commit title." -m "who &emsp; cares "
<span>[main a9f9368]  WIP: My bad commit title.</span>

# Run gitlint!
gitlint
```

```bash
1: T3 Title has trailing punctuation (.): " WIP: My bad commit title."
                  1: T5 Title contains the word 'WIP' (case-insensitive): " WIP: My bad commit title."
                  1: T6 Title has leading whitespace: " WIP: My bad commit title."
                  3: B2 Line has trailing whitespace: "who &emsp; cares "
                  3: B3 Line contains hard tab characters (\t): "who &emsp; cares "
                  3: B5 Body message is too short (10<20): "who &emsp; cares "
```

--------------------------------

### Install Gitlint from GitHub Source (Pinned Dependencies)

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Install gitlint from a GitHub source archive URL using pip, with pinned dependencies. Ensure the GITLINT_VERSION environment variable is set.

```sh
# Set version to install
export GITLINT_VERSION="v0.20.0"

# Install using pinned dependencies
pip install "gitlint-core [trusted-deps] @ https://github.com/jorisroovers/gitlint/archive/$GITLINT_VERSION.tar.gz#subdirectory=gitlint-core"
```

--------------------------------

### Example Gitlint Output with Contrib Rules

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/contrib_rules.md

This example demonstrates the output of gitlint when certain contrib rules are active and violated. It shows specific rule IDs and violation messages.

```sh
$ gitlint
1: CC1 Body does not contain a 'Signed-off-by' line
1: CL1 Title does not start with one of fix, feat, chore, docs, style, refactor, perf, test: "WIP: This is the title of a commit message."
```

--------------------------------

### Define a Rule with Multiple Options

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/options.md

Example demonstrating how to define a rule with multiple options, including integer and boolean types.

```python
options_spec = [
    IntOption("max-lint-count", 3, "Maximum body line count"),
    BoolOption("count-signoff-by", True, "Include 'Sign-off By' lines in count"),
    # etc
]
```

--------------------------------

### Install Gitlint Dev Build

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/contributing/releases.md

Install a development build of gitlint by specifying a dev build version. Find the latest dev build version on the PyPI history page.

```sh
# Find latest dev build on https://pypi.org/project/gitlint/#history
pip install gitlint=="0.19.0.dev68"
```

--------------------------------

### Configure Title Regex Matching

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Use this snippet to enforce a specific regex pattern for commit message titles. The example ensures titles start with a user-story identifier.

```ini
# Ensure every title starts with a user-story identifier like US123
[title-match-regex]
regex=^US[1-9][0-9]*
```

--------------------------------

### Configure Rule Option via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/options.md

Example of configuring a rule option using the gitlint command-line interface.

```sh
gitlint -c body-max-line-count.max-line-count=1
```

--------------------------------

### Get and Echo Gitlint Release Version

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Retrieve the current release version using Hatch and display it.

```sh
export GITLINT_RELEASE_VERSION=$(hatch version); echo $GITLINT_RELEASE_VERSION
```

--------------------------------

### Install and Use Gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/getting_started.md

Install gitlint using pip and use it to check commit messages. Supports checking the last commit, all commits in a repo, specific commits, commit messages from files, and piped commit messages.

```sh
# Install gitlint
pip install gitlint # (1)

# Check the last commit message
gitlint
# Lint all commits in your repo
gitlint --commits HEAD # (2)
# Lint specific single commit
gitlint --commit abc123

# Read the commit-msg from a file
gitlint --msg-filename examples/commit-message-2
# Pipe a commit message to gitlint
git log -1 --pretty=%B | gitlint
```

```sh
# Install gitlint commit-msg hook
gitlint install-hook # (3)
```

--------------------------------

### Define a Rule with Various Option Types

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/options.md

Example showcasing the definition of a rule with multiple option types including string, integer, boolean, list, path, and regex.

```python
options_spec = [
    StrOption("my-str-option", "default", "Fancy string option"),
    IntOption("my-int-option", 3, "Fancy integer option", allow_negative=True),
    BoolOption("my-bool-option", False, "Fancy boolean option"),
    ListOption("my-list-option"), ["foo", "bar"], "Fancy list option"
    PathOption("my-regex-option", "/foo/bar", "Fancy path option", type="dir"),
    RegexOption("my-regex-option", "^(foo|bar)", "Fancy regex option"),
]
```

--------------------------------

### Define a Configurable Commit Rule

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/options.md

Example of a `CommitRule` with an `IntOption` for maximum body line count. This allows users to configure the maximum number of lines allowed in the commit body.

```python
from gitlint.rules import CommitRule
from gitlint.options import IntOption

class BodyMaxLineCount(CommitRule):
    # A rule MUST have a human friendly name
    name = "body-max-line-count"

    # A rule MUST have a *unique* id
    # we recommend starting with UC (for User-defined Commit-rule).
    id = "UC1"

    # A rule MAY have an option_spec if its behavior is configurable.
    options_spec = [
        IntOption(
            "max-line-count",  # option name
            3,  # default value
            "Maximum body line count",  # description
        )
    ]

    def validate(self, commit):
        line_count = len(commit.message.body)
        max_count = self.options["max-line-count"].value
        if line_count > max_count:
            msg = f"Body has too many lines ({line_count} > {max_count})"
            return [RuleViolation(self.id, msg, line_nr=1)]
```

--------------------------------

### Implement CommitRule Validation in Python

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/violations.md

This example shows a typical `validate` method for a `CommitRule`. It iterates through the commit body, checks for a specific string, and returns a `RuleViolation` if found.

```python
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 []
```

--------------------------------

### Example commit message violation output

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

Illustrates the output when a commit message violates a user-defined rule, specifically the 'Signed-off-by' rule (UC2).

```sh
$ cat examples/commit-message-1 | gitlint --extra-path examples/
1: UC2 Body does not contain a 'Signed-off-by Line' # (1)
```

--------------------------------

### Gitlint Output with Named Rules

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/named_rules.md

Example output from gitlint showing violations from both default and named instances of the 'title-must-not-contain-word' rule.

```sh
$ gitlint
1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:This-Can_Be*Whatever$YouWant Title contains the word 'wonderwoman' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:extra-words Title contains the word 'foo' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:extra-words Title contains the word 'bar' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:more-words Title contains the word 'hur' (case-insensitive): "WIP: foo wonderwoman hur bar"
```

--------------------------------

### Example User-Defined Rule: SignedOffBy

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

A Python class implementing a custom gitlint commit rule that checks for the presence of a 'Signed-off-by' line in the commit body. This rule is identified by 'UC2'.

```python
from gitlint.rules import CommitRule, RuleViolation

class SignedOffBy(CommitRule):
    """Enforce that each commit contains a "Signed-off-by" line.
    We keep things simple here and just check whether the commit body
    contains a line that starts with "Signed-off-by".
    """

    # A rule MUST have a human friendly name
    name = "body-requires-signed-off-by"

    # A rule MUST have a *unique* id
    # We recommend starting with UC (for User-defined Commit-rule).
    id = "UC2"

    def validate(self, commit):
        log_msg = "This will be visible when running `gitlint --debug`"
        self.log.debug(log_msg)

        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)]
```

--------------------------------

### Configure Minimum Title Length

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Use this snippet to set a minimum character length for commit message titles. The example enforces a minimum length of 3 characters.

```ini
# Titles should be min 3 chars
[title-min-length]
min-length=3
```

--------------------------------

### Gitlint Help Command

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/cli.md

Display all available commands and options for gitlint, including general options, configuration flags, and specific commands.

```no-highlight
$ gitlint --help
Usage: gitlint [OPTIONS] COMMAND [ARGS]...

  Git lint tool, checks your git commit messages for styling issues

  Documentation: https://jorisroovers.github.io/gitlint

Options:
  --target DIRECTORY       Path of the target git repository. [default:
                           current working directory]
  -C, --config FILE        Config file location [default: .gitlint]
  -c TEXT                  Config flags in format <rule>.<option>=<value>
                           (e.g.: -c T1.line-length=80). Flag can be
                           used multiple times to set multiple config values.
  --commit TEXT            Hash (SHA) of specific commit to lint.
  --commits TEXT           The range of commits (refspec or comma-separated
                           hashes) to lint. [default: HEAD]
  -e, --extra-path PATH    Path to a directory or python module with extra
                           user-defined rules
  --ignore TEXT            Ignore rules (comma-separated by id or name).
  --contrib TEXT           Contrib rules to enable (comma-separated by id or
                           name).
  --msg-filename FILENAME  Path to a file containing a commit-msg.
  --ignore-stdin           Ignore any stdin data. Useful for running in CI
                           server.
  --staged                 Attempt smart guesses about meta info (like
                           author name, email, branch, changed files, etc)
                           for staged commits.
  --fail-without-commits   Hard fail when the target commit range is empty.
  -v, --verbose            Verbosity, more v's for more verbose output
                           (e.g.: -v, -vv, -vvv). [default: -vvv]
  -s, --silent             Silent mode (no output).
                           Takes precedence over -v, -vv, -vvv.
  -d, --debug              Enable debugging output.
  --version                Show the version and exit.
  --help                   Show this message and exit.

Commands:
  generate-config  Generates a sample gitlint config file.
  install-hook     Install gitlint as a git commit-msg hook.
  lint             Lints a git repository [default command]
  run-hook         Runs the gitlint commit-msg hook.
  uninstall-hook   Uninstall gitlint commit-msg hook.

  When no COMMAND is specified, gitlint defaults to 'gitlint lint'.

```

--------------------------------

### Deploy Gitlint Documentation

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Command to deploy the documentation using mkdocs.

```sh
mkdocs gh-deploy
```

--------------------------------

### Build and Upload Gitlint to PyPI

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Instructions to navigate to the top-level directory, clean previous builds, create distributions for gitlint, and upload to PyPI.

```sh
# Make sure you're at the top-level gitlint directory
cd ..
# remove any previous builds
./run_tests.sh --clean
# Do a rebuild
python setup.py sdist bdist_wheel
# Upload to pypitest 
twine upload dist/*
```

--------------------------------

### Clean, Build, and Publish gitlint

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Navigate back to the root directory, clean previous builds, build the package, and publish it to the test repository.

```sh
cd .. # gitlint
hatch clean
hatch build
hatch publish -r test
```

--------------------------------

### Clean, Build, and Publish gitlint-core

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Navigate to the gitlint-core directory, clean previous builds, build the package, and publish it to the test repository.

```sh
cd gitlint-core
hatch clean
hatch build
hatch publish -r test
```

--------------------------------

### Build and Upload gitlint-core to PyPI

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Steps to clean previous builds, create source and wheel distributions for gitlint-core, and upload them to PyPI using twine.

```sh
# remove any previous builds
./run_tests.sh --clean
# Do a rebuild
cd gitlint-core
python setup.py sdist bdist_wheel
# Upload to pypitest 
twine upload dist/*
```

--------------------------------

### Specify Configuration File

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Roadmap

Use the `--config` parameter to specify a custom configuration file for gitlint.

```bash
--config
```

--------------------------------

### Build Gitlint Packages Locally

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/contributing/packaging.md

Use these commands to build the gitlint and gitlint-core packages locally. Run `hatch build` to create the package and `hatch clean` to remove build artifacts.

```shell
# gitlint
hatch build
hatch clean # cleanup
```

```shell
# gitlint-core
cd gitlint-core
hatch build
hatch clean # cleanup
```

--------------------------------

### Generate a .gitlint Config File

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Roadmap

Use the `--generate-config` option to create a default .gitlint configuration file.

```bash
--generate-config
```

--------------------------------

### Build and Upload gitlint-core to TestPyPI

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Steps to clean previous builds, create source and wheel distributions, and upload the gitlint-core package to the test.pypi.org repository.

```shell
# remove any previous builds
./run_tests.sh --clean
# Do a rebuild
cd gitlint-core
python setup.py sdist bdist_wheel
# Upload to pypitest 
twine upload -r pypitest dist/*
```

--------------------------------

### Run Gitlint with Docker

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Run gitlint using a Docker image. Mount the current directory to the container and use --ulimit to avoid Docker limitations.

```sh
docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint # (1)
```

--------------------------------

### CommitRule Example: Enforce Signed-off-by Line

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/line_and_commit_rules.md

This CommitRule checks if the commit body contains a 'Signed-off-by' line. The validate method receives the entire commit object. Use `gitlint --debug` to see debug logs.

```python
from gitlint.rules import CommitRule, RuleViolation

class SignedOffBy(CommitRule):
    """Enforce that each commit contains a "Signed-off-by" line.
    We keep things simple here and just check whether the commit body
    contains a line that starts with "Signed-off-by".
    """

    # A rule MUST have a human friendly name
    name = "body-requires-signed-off-by"

    # A rule MUST have a *unique* id
    # We recommend starting with UC (for User-defined Commit-rule).
    id = "UC2"

    def validate(self, commit): # (1)
        log_msg = "This will be visible when running `gitlint --debug`"
        self.log.debug(log_msg)

        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)]
```

--------------------------------

### Build and Upload gitlint to TestPyPI

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Steps to clean previous builds, create source and wheel distributions, and upload the main gitlint package to the test.pypi.org repository from the top-level directory.

```shell
# Make sure you're at the top-level gitlint directory
cd ..
# remove any previous builds
./run_tests.sh --clean
# Do a rebuild
python setup.py sdist bdist_wheel
# Upload to pypitest 
twine upload -r pypitest dist/*
```

--------------------------------

### LineRule Example: Disallow Special Characters in Title

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/line_and_commit_rules.md

This LineRule prevents specific special characters from appearing in the commit message title. It demonstrates configurable options using `ListOption`. The validate method receives the line and commit object. Use `gitlint --debug` to see debug logs.

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

class SpecialChars(LineRule):
    """This rule will enforce that the commit message title does not
    contain any of the following characters: $^%@!*()
    """

    # A rule MUST have a human friendly name
    name = "title-no-special-chars"

    # A rule MUST have a *unique* id.
    # We recommend starting with UL (for User-defined Line-rule)
    id = "UL1"

    # A line-rule MUST have a target (not required for CommitRules).
    target = CommitMessageTitle # (1)

    # A rule MAY have an option_spec if its behavior should be configurable.
    options_spec = [
        ListOption(
            "special-chars", # option name
            ["$", "^", "%", "@", "!", "*", "(", ")"], # default value
            "Comma separated list of chars that cannot occur in the title",
        )
    ]

    def validate(self, line, _commit): # (2)
        self.log.debug("This will be visible when running `gitlint --debug`")

        violations = []
        # Options can be accessed by name lookup in self.options
        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
```

--------------------------------

### Specify Development Dependencies

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Ensure the development dependencies in pyproject.toml match the version in gitlint-core/__init__.py.

```toml
dependencies = [
    "gitlint-core[trusted-deps]==0.19.0dev2",
]
```

--------------------------------

### Configure Gitlint with .gitlint File

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/index.md

Use a .gitlint file to set general options, ignore/enable rules, specify extra paths for custom rules, and configure specific rule parameters. Rules can be referenced by name or ID.

```ini
[general]
# Ignore rules, reference them by id or name (comma-separated)
ignore=title-trailing-punctuation, T3

# Enable specific community contributed rules
contrib=contrib-title-conventional-commits,CC1

# Set the extra-path where gitlint will search for user defined rules
extra-path=./gitlint_rules/my_rules.py

### Configuring rules ### (1)

[title-max-length]
line-length=80 

[title-min-length]
min-length=5
```

```ini
[T1]
line-length=80
```

--------------------------------

### Enable Contrib Rules via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Use the --contrib flag to specify contrib rules directly on the command line. This allows for quick testing or overriding .gitlint configurations.

```sh
gitlint --contrib=contrib-title-conventional-commits,CC1
# different way of doing the same
gitlint -c general.contrib=contrib-title-conventional-commits,CC1
```

--------------------------------

### Define a User-Defined Configuration Rule in Python

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/configuration_rules.md

This Python snippet demonstrates how to create a custom configuration rule for Gitlint. It shows how to define the rule's name, ID, and configurable options, and how to implement the `apply` method to modify Gitlint's configuration or the commit message based on specific conditions.

```python
from gitlint.rules import ConfigurationRule
from gitlint.options import IntOption

class ReleaseConfigurationRule(ConfigurationRule):
    """
    This rule will modify gitlint's behavior for Release Commits.

    This example might not be the most realistic for a real-world scenario,
    but is meant to give an overview of what's possible.
    """

    # A rule MUST have a human friendly name
    name = "release-configuration-rule"

    # A rule MUST have a *unique* id
    # We recommend starting with UCR (for User-defined Configuration-Rule)
    id = "UCR1"

    # A rule MAY have an option_spec if its behavior should be configurable.
    options_spec = [
        IntOption("custom-verbosity", 2, "Verbosity for release commits"),
    ]

    def apply(self, config, commit):
        self.log.debug("This will be visible when running `gitlint --debug`")

        # If the commit title starts with 'Release', we want to modify
        # how all subsequent rules interpret that commit
        if commit.message.title.startswith("Release"):

            # If your Release commit messages are auto-generated, the
            # body might contain trailing whitespace. Let's ignore that
            config.ignore.append("body-trailing-whitespace")

            # Similarly, the body lines might exceed 80 chars,
            # let's set gitlint's limit to 99
            # To set rule options use:
            # config.set_rule_option(<rule-name>, <rule-option>, <value>)
            config.set_rule_option("body-max-line-length", "line-length", 99)

            # For kicks, let's set gitlint's verbosity to 2
            # To set general options use
            # config.set_general_option(<general-option>, <value>)
            config.set_general_option("verbosity", 2)
            # We can also use custom options to make this configurable
            custom_verbosity = self.options["custom-verbosity"].value
            config.set_general_option("verbosity", custom_verbosity)

            # Strip any lines starting with $ from the commit message
            # (this only affects how gitlint sees your commit message,
            # it does NOT modify your actual commit in git)
            body = [l for l in commit.message.body if not l.startswith("$")]
            commit.message.body = body

            # You can add any extra properties you want to the commit object,
            # these will be available later on in all rules.
            commit.my_property = "This is my property"

```

--------------------------------

### Build and Publish Gitlint Docker Image

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Commands to build Docker images for gitlint, tag them with the version and 'latest', perform sanity tests, and push them to Docker Hub.

```sh
# NOTE: These docker images perform a 'pip install', so its assumed that 
# the version passed via `GITLINT_VERSION` is available for installation on pypi.
export GITLINT_VERSION=`python3 -c "import gitlint; print(gitlint.__version__)"`; echo $GITLINT_VERSION
docker rm jorisroovers/gitlint:$GITLINT_VERSION # remove any previous builds
docker build --build-arg GITLINT_VERSION=$GITLINT_VERSION -t jorisroovers/gitlint:$GITLINT_VERSION .
docker build --build-arg GITLINT_VERSION=$GITLINT_VERSION -t jorisroovers/gitlint:latest .

# Local copy Sanity test
docker run -v $(pwd):/repo jorisroovers/gitlint:$GITLINT_VERSION --version
docker run -v $(pwd):/repo jorisroovers/gitlint:$GITLINT_VERSION --debug
docker run -v $(pwd):/repo jorisroovers/gitlint:latest --version
docker run -v $(pwd):/repo jorisroovers/gitlint:latest --debug
docker run -v $(pwd):/repo jorisroovers/gitlint --version
docker run -v $(pwd):/repo jorisroovers/gitlint --debug

# Login and push to dockerhub
docker login -u jorisroovers
docker push jorisroovers/gitlint:$GITLINT_VERSION
docker push jorisroovers/gitlint:latest
# Check results at https://hub.docker.com/r/jorisroovers/gitlint/tags

# Remove local copies
docker image rm -f jorisroovers/gitlint:$GITLINT_VERSION
docker image rm -f jorisroovers/gitlint:latest
docker image rm -f jorisroovers/gitlint


# Pull image from dockerhub and test again
docker run -v $(pwd):/repo jorisroovers/gitlint:$GITLINT_VERSION --version
docker run -v $(pwd):/repo jorisroovers/gitlint:$GITLINT_VERSION --debug
docker run -v $(pwd):/repo jorisroovers/gitlint:latest --version
docker run -v $(pwd):/repo jorisroovers/gitlint:latest --debug
docker run -v $(pwd):/repo jorisroovers/gitlint --version
docker run -v $(pwd):/repo jorisroovers/gitlint --debug
```

--------------------------------

### Enable Gitlint Fish Shell Completion

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Enable shell completion for gitlint in Fish by adding the provided command to your ~/.config/fish/completions/foo-bar.fish file.

```sh
# Fish: add to ~/.config/fish/completions/foo-bar.fish
eval (env _GITLINT_COMPLETE=fish_source gitlint)
```

--------------------------------

### Enable Regex Search Semantics via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

This command-line invocation shows how to enable `regex-style-search` for gitlint, ensuring that regular expression matching uses `re.search()` semantics.

```sh
gitlint -c general.regex-style-search=true

```

--------------------------------

### Configure Options with -c Flag

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/cli.md

Use the `-c` flag to set general and rule-specific options. Multiple `-c` flags can be used to set multiple values.

```sh
gitlint -c general.silent=true -c title-max-length.line-length=80

```

--------------------------------

### Set Hatch Index Authentication

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Export environment variables for username and password to authenticate with the Hatch index.

```sh
export HATCH_INDEX_USER=<username>
export HATCH_INDEX_AUTH=<password>
```

--------------------------------

### Configure extra-path via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

Provide the path to user-defined rules using the `--extra-path` flag or the `-c` configuration flag on the command line. Paths are relative to the current working directory.

```sh
gitlint --extra-path "tools/gitlint/myrules" # (1)
# Alternatively, point to a specific file
gitlint --extra-path "tools/gitlint/myrules/my_rules.py"
```

```sh
# You can also use -c style config flags
gitlint -c general.extra-path=tools/gitlint/myrules
```

```sh
# You can also use absolute paths of course
gitlint --extra-path "/opt/gitlint/my_rules.py"
```

--------------------------------

### Enable Contrib Rules via Environment Variable

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/contrib_rules.md

Alternatively, contrib rules can be enabled by setting the GITLINT_CONTRIB environment variable.

```sh
GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint
```

--------------------------------

### Enable Contrib Rules via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/contrib_rules.md

Contrib rules can be enabled directly from the command line using the --contrib flag.

```sh
gitlint --contrib contrib-title-conventional-commits,CC1
```

--------------------------------

### Enable Contrib Rules in .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Configure which contrib rules to enable by listing their names or IDs in the .gitlint file. This is useful for customizing linting behavior beyond built-in rules.

```ini
[general]
contrib=contrib-title-conventional-commits,CC1
```

--------------------------------

### Configure Gitlint with CLI Flags

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/index.md

Control gitlint's verbosity, ignore specific rules, enable debug mode, or load user-defined rules directly from the command line. Configuration options can also be set using the -c flag.

```sh
# Change gitlint's verbosity.
$ gitlint -v
# Ignore certain rules
$ gitlint --ignore body-is-missing,T3
# Enable debug mode
$ gitlint --debug
# Load user-defined rules
$ gitlint --extra-path /home/joe/mygitlint_rules
# Set any config option using -c
$ gitlint -c general.verbosity=2 -c title-max-length.line-length=80
```

--------------------------------

### Running gitlint with --debug to discover rules

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

Use the `--debug` flag with gitlint to see which rules, including user-defined ones, are being discovered and loaded. This is helpful for troubleshooting rule discovery.

```sh
$ gitlint --debug --extra-path examples/
# [output cut for brevity]
  UC1: body-max-line-count
     body-max-line-count=3
  UC2: body-requires-signed-off-by
  UL1: title-no-special-chars
     special-chars=['$', '^', '%', '@', '!', '*', '(', ')']
```

--------------------------------

### Enable Contrib Rules in .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/contrib_rules.md

To enable contrib rules, you must add them to the [general] section of your .gitlint configuration file. Simply configuring them below that section is not sufficient.

```ini
[general]
# You HAVE to add the rule to [general] to enable it
# Only configuring (such as below) does NOT enable it.
contrib = contrib-title-conventional-commits,CC1

# Setting contrib rule options is identical to configuring other rules 
[contrib-title-conventional-commits]
types = bugfix,user-story,epic
```

--------------------------------

### Tag Git Commit for Release

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP

Commands to create a Git tag for the current version, list all tags, and push the tags to the remote repository.

```bash
export GITLINT_VERSION_TAG=v`python3 -c "import gitlint; print(gitlint.__version__)"`; echo $GITLINT_VERSION_TAG
git tag $GITLINT_VERSION_TAG
git tag --list
git push --tags
```

--------------------------------

### Enable Regex Search Semantics

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Configure gitlint to use `re.search()` semantics instead of `re.match()` for built-in rules that use regular expressions. This ensures matches can occur anywhere in the string, not just at the beginning.

```ini
[general]
regex-style-search=true

```

--------------------------------

### Work on a Different Git Repo

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Roadmap

Use the `--target` parameter to specify a different git repository directory for gitlint operations.

```bash
--target
```

--------------------------------

### Configure extra-path in .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

Specify the directory or file containing user-defined rules in the `.gitlint` configuration file. This path is relative to the current working directory.

```ini
[general]
extra-path=tools/gitlint/myrules # (1)

# Alternatively, point to a specific file
[general]
extra-path=tools/gitlint/myrules/my_rules.py
```

```ini
# You can also use absolute paths of course
[general]
extra-path=/opt/gitlint/my_rules.py
```

--------------------------------

### Enable Gitlint Bash Shell Completion

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Enable shell completion for gitlint in Bash by adding the provided command to your ~/.bashrc file.

```sh
# Bash: add to ~/.bashrc
eval "$(_GITLINT_COMPLETE=bash_source gitlint)"
```

--------------------------------

### Enable Gitlint Zsh Shell Completion

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Enable shell completion for gitlint in Zsh by adding the provided command to your ~/.zshrc file.

```sh
# Zsh: add to ~/.zshrc
eval "$(_GITLINT_COMPLETE=zsh_source gitlint)"
```

--------------------------------

### Configure Gitlint with Environment Variables

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/index.md

Set gitlint's verbosity, ignore rules, enable debug mode, or specify paths for user-defined rules using environment variables. This method is useful for CI/CD environments.

```sh
# Change gitlint's verbosity.
$ GITLINT_VERBOSITY=1 gitlint
# Ignore certain rules
$ GITLINT_IGNORE="body-is-missing,T3" gitlint
# Enable debug mode
$ GITLINT_DEBUG=1 --debug
# Load user-defined rules
$ GITLINT_EXTRA_PATH="/home/joe/mygitlint_rules" gitlint
```

--------------------------------

### Configure body-min-length

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Set the minimum required character count for commit message bodies. This allows for shorter messages than the default.

```ini
# You want *something* in every commit body, but doesn't have to be as long as 20 chars.
[body-min-length]
min-length=5
```

```ini
# You want a more elaborate message in every commit body
[body-min-length]
min-length=100
```

--------------------------------

### Bump Version with Hatch

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Release-MOP--Hatch

Increment the version of the project using Hatch, specifying a minor bump and marking it as a development version.

```sh
hatch version minor,dev
```

--------------------------------

### Configure extra-path via Environment Variable

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/user_defined_rules/index.md

Set the `GITLINT_EXTRA_PATH` environment variable to specify the directory or file containing user-defined rules. Paths are relative to the current working directory.

```sh
GITLINT_EXTRA_PATH=tools/gitlint/myrules gitlint # (1)
# Alternatively, point to a specific file
GITLINT_EXTRA_PATH=tools/gitlint/myrules/my_rules.py gitlint
```

```sh
# You can also use absolute paths of course
GITLINT_EXTRA_PATH=/opt/gitlint/myrules gitlint
```

--------------------------------

### Configure Named Rules in .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/named_rules.md

Define additional instances of the 'title-must-not-contain-word' rule with custom names and options. This demonstrates using both the rule name and ID for configuration.

```ini
[title-must-not-contain-word:extra-words]
words=foo,bar

[T5:more-words]
words=hur,dur

[title-must-not-contain-word:This-Can_Be*Whatever$YouWant]
words=wonderwoman,batman,power ranger
```

--------------------------------

### Configure Body Regex Match (INI)

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Use this rule to enforce that the commit body matches a specific regular expression. Configure the 'regex' option within the [body-match-regex] section.

```ini
# Ensure the body ends with Reviewed-By: <some value>
[body-match-regex]
regex=Reviewed-By:(.*)$

# Ensure body contains the word "Foo" somewhere
[body-match-regex]
regex=(*.)Foo(.*)
```

--------------------------------

### Enable Fail on Empty Commit Range

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Use this configuration to make gitlint exit with a non-zero status code when the commit range provided is valid but empty. This is useful for enforcing that commits must exist.

```ini
[general]
fail-without-commits=true

```

--------------------------------

### Configure Maximum Title Length

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Set a custom maximum length for commit titles using the 'line-length' option within the 'title-max-length' configuration section.

```ini
# It's the 21st century, titles can be 120 chars long!
[title-max-length]
line-length=120
```

--------------------------------

### Configure body-max-line-length

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

Set the maximum allowed line length for commit message bodies. This configuration overrides the default limit.

```ini
# It's the 21st century, lines can be 120 chars long
[body-max-line-length]
line-length=120
```

--------------------------------

### Mute Output and Lint Specific Commit via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/cli.md

Use the `--silent` flag to mute all output or `--commit` to lint a specific commit using the command line.

```sh
# Mute all output
gitlint --silent

# Lint a specific commit
gitlint --commit abc123

```

--------------------------------

### Uninstall Gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/installation.md

Fully uninstall gitlint by removing both the main gitlint package and gitlint-core using pip.

```sh
pip uninstall gitlint gitlint-core
```

--------------------------------

### Enable Staged Commit Detection via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Use the --staged flag or the -c general.staged=true option to enable staged commit detection on the command line. This allows Gitlint to infer commit details when no actual git commit exists.

```sh
gitlint --staged
gitlint -c general.staged=true # different way of doing the same
```

--------------------------------

### Shell Script to Lint Arbitrary Commits

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/linting_specific_commits.md

Use a shell script to iterate over commits from `git rev-list` and lint each one individually with `gitlint --commit`. This approach incurs Gitlint startup time per commit, making it slower for large sets.

```sh
#!/bin/sh

for commit in $(git rev-list my-branch); do
    echo "Commit $commit"
    gitlint --commit $commit
    echo "--------"
done
```

--------------------------------

### Configure Gitlint to Not Ignore Revert Commits via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Specify -c general.ignore-revert-commits=false on the command line to include revert commits in the linting process.

```sh
gitlint -c general.ignore-revert-commits=false
```

--------------------------------

### Configure Gitlint to Ignore Stdin via CLI

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

You can disable standard input processing directly from the command line using the --ignore-stdin flag or by setting the general.ignore-stdin configuration option.

```sh
gitlint --ignore-stdin
gitlint -c general.ignore-stdin=true
```

--------------------------------

### Configure Author Email Regex (INI)

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/builtin_rules.md

This rule validates the author's email address against a provided regular expression. Customize the 'regex' option in the [author-valid-email] section to define allowed email patterns.

```ini
# Only allow email addresses from a foo.com domain
[author-valid-email]
regex=[^@]+@foo.com
```

--------------------------------

### Configure Gitlint to Ignore Stdin via Environment Variable

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/configuration/general_options.md

Set the GITLINT_IGNORE_STDIN environment variable to '1' to achieve the same effect as the --ignore-stdin CLI flag.

```sh
GITLINT_IGNORE_STDIN=1 gitlint
```

--------------------------------

### Specify Commit ID for Linting

Source: https://github.com/jorisroovers/gitlint/wiki/[ARCHIVE]-Roadmap

Use the `--commits` option to specify a commit ID or revspec for linting.

```bash
--commits {revspec}
```

--------------------------------

### Configure Contrib Rule Types in .gitlint

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/rules/contrib_rules.md

This configuration snippet shows how to set specific options for the 'contrib-title-conventional-commits' rule within a .gitlint file. The 'types' option allows you to specify a comma-separated list of allowed commit types.

```ini
[contrib-title-conventional-commits]
types=bugfix,user-story,epic
```

--------------------------------

### Lint a Single Commit

Source: https://github.com/jorisroovers/gitlint/blob/main/docs/linting_specific_commits.md

Use the `--commit` flag to lint a specific commit. Short SHAs, special references like HEAD~2, and branch names are also supported.

```sh
gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16
```

```sh
gitlint --commit 019cf40  # short SHAs work too
```

```sh
gitlint --commit HEAD~2   # as do special references
```

```sh
gitlint --commit mybranch # lint latest commit on a branch 
```