gitlint

Check the last commit message

$ gitlint

$ gitlint --commits [single_refspec_argument]

$ gitlint --extra-path [path/to/directory]

$ gitlint --target [path/to/target_directory]

$ gitlint --msg-filename [path/to/filename]

$ gitlint --staged

gitlint [OPTIONS] [COMMIT_RANGE]

-c CONFIG_KEY=CONFIG_VALUE, --config CONFIG_KEY=CONFIG_VALUE
    Sets a specific configuration value directly on the command line. This overrides values from configuration files and can be used multiple times.

--config FILE
    Loads configuration settings from the specified file. This file typically contains rule settings, ignore lists, and more.

--extra-path PATH
    Specifies a directory from which to load extra user-defined rules. This allows for custom linting logic to be applied.

--msg-filename FILE
    Lints the commit message contained in the specified file. Useful for testing or linting messages generated by other processes.

--msg-filename-stdin
    Reads the commit message from standard input, treating it as if it came from a file. Useful for piping file contents.

--msg-stdin
    Reads the commit message directly from standard input. This is typically used when piping a message string.

--commit COMMIT_HASH
    Lints the commit message of a specific commit identified by its hash.

--commits COMMIT_RANGE
    Lints commit messages within the specified Git commit range (e.g., `HEAD~3..HEAD`). Accepts arguments in a format similar to `git rev-list`.

--staged
    Lints the commit message that is currently staged for commit (typically found in `.git/COMMIT_EDITMSG`). This option is frequently used when gitlint is invoked from a Git `commit-msg` hook.

--ignore RULE_ID_OR_NAME
    Ignores one or more specific rules by their ID (e.g., `T1`) or name (e.g., `body-max-line-length`). This option can be specified multiple times to ignore several rules.

--strict
    Causes gitlint to exit with a non-zero status code if any violations (errors or warnings) are found. By default, it exits with a non-zero code only for errors.

--silent
    Suppresses all output if no violations are found. Output is only displayed when there are issues with the commit message.

--json
    Outputs the linting results in JSON format, which is ideal for programmatic consumption and integration with other tools or scripts.

--verbose
    Provides more detailed output, showing additional information about the rules being checked and their status during the linting process.

--debug
    Prints extensive debugging information, useful for troubleshooting issues with gitlint itself or understanding its internal workings.

--version
    Displays the gitlint program's version number and then exits.

--help
    Displays the help message for gitlint, including a list of options and usage examples, and then exits.

gitlint is a powerful and highly configurable command-line tool designed to lint Git commit messages. It helps developers ensure their commit messages adhere to specific standards and conventions, promoting consistency, readability, and maintainability across a project's commit history.

It comes with a set of default rules (e.g., subject line length, capitalization, imperative mood, body line length) that can be enabled, disabled, or configured. gitlint can lint the last commit, a range of commits, or a commit message from a file or stdin. It's often integrated into Git hooks, such as `commit-msg` or `pre-commit`, to enforce message quality automatically before a commit is created.

gitlint is a Python-based tool, thus requiring a Python interpreter to be installed on the system. It also depends on Git being installed and accessible in the system's PATH. While highly configurable, setting up complex custom rules or advanced integrations might require familiarity with Python programming and Git hook mechanisms. It solely focuses on commit message formatting and does not analyze code quality.

gitlint is most commonly integrated into Git's client-side hooks, particularly the `commit-msg` hook. By placing gitlint within this hook, it automatically lints commit messages before they are finalized, preventing non-compliant messages from ever being committed. It can also be utilized in `pre-commit` hooks for more general pre-commit checks or as part of CI/CD pipelines to validate commit messages before merging.

Beyond command-line options, gitlint offers persistent configuration via dedicated files. It primarily looks for a `.gitlint` file (using an INI-like format) or a `pyproject.toml` file in the repository's root or user's home directory. This allows project-specific rules, ignored rules, and other settings to be easily defined, shared, and version-controlled within a repository, ensuring consistent linting behavior across team members.

gitlint emerged as an open-source solution to standardize Git commit messages within development teams, aiming to improve the clarity and consistency of project histories. Its development focused on providing a flexible and easy-to-use tool for enforcing best practices in commit message hygiene. Since its inception, it has gained traction due to its straightforward configuration, extensibility, and effectiveness in maintaining clean commit logs.

git(1), githooks(5)