Signed-off-by: Daniel Baumann <daniel@debian.org>

2025-02-13 06:06:24 +01:00

21 KiB

Raw Permalink Blame History

Configuration

Gitlint can be configured through different means.

The .gitlint file

You can modify gitlint's behavior by adding a .gitlint file to your git repository.

Generate a default .gitlint config file by running:

gitlint generate-config

You can also use a different config file like so:

gitlint --config myconfigfile.ini

The block below shows a sample .gitlint file. Details about rule config options can be found on the Rules page, details about the [general] section can be found in the General Configuration section of this page.

# Edit this file as you like.
#
# All these sections are optional. Each section with the exception of [general] represents
# one rule and each key in it is an option for that specific rule.
#
# Rules and sections can be referenced by their full name or by id. For example
# section "[body-max-line-length]" could also be written as "[B1]". Full section names are
# used in here for clarity.
# Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/
#
# Use 'gitlint generate-config' to generate a config file with all possible options
[general]
# Ignore certain rules (comma-separated list), you can reference them by their
# id or by their full name
ignore=title-trailing-punctuation, T3

# verbosity should be a value between 1 and 3, the commandline -v flags take
# precedence over this
verbosity = 2

# By default gitlint will ignore merge, revert, fixup, fixup=amend, and squash commits.
ignore-merge-commits=true
ignore-revert-commits=true
ignore-fixup-commits=true
ignore-fixup-amend-commits=true
ignore-squash-commits=true

# Ignore any data sent to gitlint via stdin
ignore-stdin=true

# Fetch additional meta-data from the local repository when manually passing a
# commit message to gitlint via stdin or --commit-msg. Disabled by default.
staged=true

# Hard fail when the target commit range is empty. Note that gitlint will
# already fail by default on invalid commit ranges. This option is specifically
# to tell gitlint to fail on *valid but empty* commit ranges.
# Disabled by default.
fail-without-commits=true

# Whether to use Python `search` instead of `match` semantics in rules that use
# regexes. Context: https://github.com/jorisroovers/gitlint/issues/254
# Disabled by default, but will be enabled by default in the future.
regex-style-search=true

# Enable debug mode (prints more output). Disabled by default.
debug=true

# Enable community contributed rules
# See http://jorisroovers.github.io/gitlint/contrib_rules for details
contrib=contrib-title-conventional-commits,CC1

# Set the extra-path where gitlint will search for user defined rules
# See http://jorisroovers.github.io/gitlint/user_defined_rules for details
extra-path=examples/

# This is an example of how to configure the "title-max-length" rule and
# set the line-length it enforces to 80
[title-max-length]
line-length=80

# Conversely, you can also enforce minimal length of a title with the
# "title-min-length" rule:
[title-min-length]
min-length=5

[title-must-not-contain-word]
# Comma-separated list of words that should not occur in the title. Matching is case
# insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING"
# will not cause a violation, but "WIP: my title" will.
words=wip

[title-match-regex]
# python like regex (https://docs.python.org/3/library/re.html) that the
# commit-msg title must be matched to.
# Note that the regex can contradict with other rules if not used correctly
# (e.g. title-must-not-contain-word).
regex=^US[0-9]*

[body-max-line-length]
line-length=120

[body-min-length]
min-length=5

[body-is-missing]
# Whether to ignore this rule on merge commits (which typically only have a title)
# default = True
ignore-merge-commits=false

[body-changed-file-mention]
# List of files that need to be explicitly mentioned in the body when they are changed
# This is useful for when developers often erroneously edit certain files or git submodules.
# By specifying this rule, developers can only change the file when they explicitly
# reference it in the commit message.
files=gitlint-core/gitlint/rules.py,README.md

[body-match-regex]
# python-style regex that the commit-msg body must match.
# E.g. body must end in My-Commit-Tag: foo
regex=My-Commit-Tag: foo$

[author-valid-email]
# python like regex (https://docs.python.org/3/library/re.html) that the
# commit author email address should be matched to
# E.g.: For example, use the following regex if you only want to allow email
# addresses from foo.com
regex=[^@]+@foo.com

[ignore-by-title]
# Ignore certain rules for commits of which the title matches a regex
# E.g. Match commit titles that start with "Release"
regex=^Release(.*)

# Ignore certain rules, you can reference them by their id or by their full name
# Use 'all' to ignore all rules
ignore=T1,body-min-length

[ignore-by-body]
# Ignore certain rules for commits of which the body has a line that matches a regex
# E.g. Match bodies that have a line that that contain "release"
regex=(.*)release(.*)
#
# Ignore certain rules, you can reference them by their id or by their full name
# Use 'all' to ignore all rules
ignore=T1,body-min-length

[ignore-body-lines]
# Ignore certain lines in a commit body that match a regex.
# E.g. Ignore all lines that start with 'Co-Authored-By'
regex=^Co-Authored-By

[ignore-by-author-name]
# Ignore certain rules for commits of which the author name matches a regex
# E.g. Match commits made by dependabot
regex=(.*)dependabot(.*)

# Ignore certain rules, you can reference them by their id or by their full name
# Use 'all' to ignore all rules
ignore=T1,body-min-length

# This is a contrib rule - a community contributed rule. These are disabled by default.
# You need to explicitly enable them one-by-one by adding them to the "contrib" option
# under [general] section above.
[contrib-title-conventional-commits]
# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
types = bugfix,user-story,epic

Commandline config

You can also use one or more -c flags like so:

$ gitlint -c general.verbosity=2 -c title-max-length.line-length=80 -c B1.line-length=100

The generic config flag format is -c <rule>.<option>=<value> and supports all the same rules and options which you can also use in a .gitlint config file.

Commit specific config

You can also configure gitlint by adding specific lines to your commit message. For now, we only support ignoring commits by adding gitlint-ignore: all to the commit message like so:

WIP: This is my commit message

I want gitlint to ignore this entire commit message.
gitlint-ignore: all

gitlint-ignore: all can occur on any line, as long as it is at the start of the line.

You can also specify specific rules to be ignored as follows:

WIP: This is my commit message

I want gitlint to ignore this entire commit message.
gitlint-ignore: T1, body-hard-tab

Configuration precedence

gitlint configuration is applied in the following order of precedence:

Commit specific config (e.g.: gitlint-ignore: all in the commit message)
Configuration Rules (e.g.: ignore-by-title)
Commandline convenience flags (e.g.: -vv, --silent, --ignore)
Environment variables (e.g.: GITLINT_VERBOSITY=3)
Commandline configuration flags (e.g.: -c title-max-length=123)
Configuration file (local .gitlint file, or file specified using -C/--config)
Default gitlint config

General Options

Below we outline all configuration options that modify gitlint's overall behavior. These options can be specified using commandline flags or in [general] section in a .gitlint configuration file.

silent

Enable silent mode (no output). Use exit code to determine result.

Default value	gitlint version	commandline flag	environment variable
`False`	>= 0.1.0	`--silent`	`GITLINT_SILENT`

Examples

# CLI
gitlint --silent
GITLINT_SILENT=1 gitlint  # using env variable

verbosity

Amount of output gitlint will show when printing errors.

Default value	gitlint version	commandline flag	environment variable
3	>= 0.1.0	`-v`	`GITLINT_VERBOSITY`

Examples

# CLI
gitlint -vvv                   # default     (level 3)
gitlint -vv                    # less output (level 2)
gitlint -v                     # even less   (level 1)
gitlint --silent               # no output   (level 0)
gitlint -c general.verbosity=1 # Set specific level
gitlint -c general.verbosity=0 # Same as --silent
GITLINT_VERBOSITY=2 gitlint    # using env variable

# .gitlint
[general]
verbosity=2

ignore

Comma separated list of rules to ignore (by name or id).

Default value	gitlint version	commandline flag	environment variable
[] (=empty list)	>= 0.1.0	`--ignore`	`GITLINT_IGNORE`

Examples

# CLI
gitlint --ignore=body-min-length              # ignore single rule
gitlint --ignore=T1,body-min-length           # ignore multiple rule
gitlint -c general.ignore=T1,body-min-length  # different way of doing the same
GITLINT_IGNORE=T1,body-min-length gitlint     # using env variable

#.gitlint
[general]
ignore=T1,body-min-length

debug

Enable debugging output.

Default value	gitlint version	commandline flag	environment variable
false	>= 0.7.1	`--debug`	`GITLINT_DEBUG`

Examples

# CLI
gitlint --debug
GITLINT_DEBUG=1 gitlint # using env variable
# --debug is special, the following does NOT work
# gitlint -c general.debug=true

target

Target git repository gitlint should be linting against.

Default value	gitlint version	commandline flag	environment variable
(empty)	>= 0.8.0	`--target`	`GITLINT_TARGET`

Examples

# CLI
gitlint --target=/home/joe/myrepo/
gitlint -c general.target=/home/joe/myrepo/  # different way of doing the same
GITLINT_TARGET=/home/joe/myrepo/ gitlint     # using env variable

#.gitlint
[general]
target=/home/joe/myrepo/

config

Path where gitlint looks for a config file.

Default value	gitlint version	commandline flag	environment variable
`.gitlint`	>= 0.1.0	`--config`	`GITLINT_CONFIG`

Examples

gitlint --config=/home/joe/gitlint.ini
gitlint -C /home/joe/gitlint.ini      # different way of doing the same
GITLINT_CONFIG=/home/joe/gitlint.ini  # using env variable

extra-path

Path where gitlint looks for user-defined rules.

Default value	gitlint version	commandline flag	environment variable
(empty)	>= 0.8.0	`--extra-path`	`GITLINT_EXTRA_PATH`

Examples

# CLI
gitlint --extra-path=/home/joe/rules/
gitlint -c general.extra-path=/home/joe/rules/  # different way of doing the same
GITLINT_EXTRA_PATH=/home/joe/rules/ gitlint     # using env variable

#.gitlint
[general]
extra-path=/home/joe/rules/

contrib

Comma-separated list of Contrib rules to enable (by name or id).

Default value	gitlint version	commandline flag	environment variable
(empty)	>= 0.12.0	`--contrib`	`GITLINT_CONTRIB`

Examples

# CLI
gitlint --contrib=contrib-title-conventional-commits,CC1
# different way of doing the same
gitlint -c general.contrib=contrib-title-conventional-commits,CC1
# using env variable
GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint

#.gitlint
[general]
contrib=contrib-title-conventional-commits,CC1

staged

Attempt smart guesses about meta info (like author name, email, branch, changed files, etc) when manually passing a commit message to gitlint via stdin or --commit-msg.

Since in such cases no actual git commit exists (yet) for the message being linted, gitlint needs to apply some heuristics (like checking git config and any staged changes) to make a smart guess about what the likely author name, email, commit date, changed files and branch of the ensuing commit would be.

When not using the --staged flag while linting a commit message via stdin or --commit-msg, gitlint will only have access to the commit message itself for linting and won't be able to enforce rules like M1:author-valid-email.

Default value	gitlint version	commandline flag	environment variable
false	>= 0.13.0	`--staged`	`GITLINT_STAGED`

Examples

# CLI
gitlint --staged
gitlint -c general.staged=true # different way of doing the same
GITLINT_STAGED=1 gitlint       # using env variable

#.gitlint
[general]
staged=true

fail-without-commits

Hard fail when the target commit range is empty. Note that gitlint will already fail by default on invalid commit ranges. This option is specifically to tell gitlint to fail on valid but empty commit ranges.

Default value	gitlint version	commandline flag	environment variable
false	>= 0.15.2	`--fail-without-commits`	`GITLINT_FAIL_WITHOUT_COMMITS`

Examples

# CLI
# The following will cause gitlint to hard fail (i.e. exit code > 0)
# since HEAD..HEAD is a valid but empty commit range.
gitlint --fail-without-commits --commits HEAD..HEAD
GITLINT_FAIL_WITHOUT_COMMITS=1 gitlint       # using env variable

#.gitlint
[general]
fail-without-commits=true

regex-style-search

Whether to use Python re.search() instead of re.match() semantics in all built-in rules that use regular expressions.

Default value	gitlint version	commandline flag	environment variable
false	>= 0.18.0	Not Available	Not Available

!!! important At this time, regex-style-search is disabled by default, but it will be enabled by default in the future.

Gitlint will log a warning when you're using a rule that uses a custom regex and this option is not enabled:

WARNING: I1 - ignore-by-title: gitlint will be switching from using Python regex 'match' (match beginning) to
'search' (match anywhere) semantics. Please review your ignore-by-title.regex option accordingly.
To remove this warning, set general.regex-style-search=True. 
More details: https://jorisroovers.github.io/gitlint/configuration/#regex-style-search

If you don't have any custom regex specified, gitlint will not log a warning and no action is needed.

To remove the warning:

Review your regex in the rules gitlint warned for and ensure it's still accurate when using re.search() semantics.
Enable regex-style-search in your .gitlint file (or using any other way to configure gitlint):

[general]
regex-style-search=true

More context

Python offers two different primitive operations based on regular expressions: re.match() checks for a match only at the beginning of the string, while re.search() checks for a match anywhere in the string.

Most rules in gitlint already use re.search() instead of re.match(), but there's a few notable exceptions that use re.match(), which can lead to unexpected matching behavior.

M1 - author-valid-email
I1 - ignore-by-title
I2 - ignore-by-body
I3 - ignore-body-lines
I4 - ignore-by-author-name

The regex-style-search option is meant to fix this inconsistency. Setting it to true will force the above rules to use re.search() instead of re.match(). For detailed context, see issue #254.

Examples

# CLI
gitlint -c general.regex-style-search=true

#.gitlint
[general]
regex-style-search=true

ignore-stdin

Ignore any stdin data. Sometimes useful when running gitlint in a CI server.

Default value	gitlint version	commandline flag	environment variable
false	>= 0.12.0	`--ignore-stdin`	`GITLINT_IGNORE_STDIN`

Examples

# CLI
gitlint --ignore-stdin
gitlint -c general.ignore-stdin=true # different way of doing the same
GITLINT_IGNORE_STDIN=1 gitlint       # using env variable

#.gitlint
[general]
ignore-stdin=true

ignore-merge-commits

Whether or not to ignore merge commits.

Default value	gitlint version	commandline flag	environment variable
true	>= 0.7.0	Not Available	Not Available

Examples

# CLI
gitlint -c general.ignore-merge-commits=false

#.gitlint
[general]
ignore-merge-commits=false

ignore-revert-commits

Whether or not to ignore revert commits.

Default value	gitlint version	commandline flag	environment variable
true	>= 0.13.0	Not Available	Not Available

Examples

# CLI
gitlint -c general.ignore-revert-commits=false

#.gitlint
[general]
ignore-revert-commits=false

ignore-fixup-commits

Whether or not to ignore fixup commits.

Default value	gitlint version	commandline flag	environment variable
true	>= 0.9.0	Not Available	Not Available

Examples

# CLI
gitlint -c general.ignore-fixup-commits=false

#.gitlint
[general]
ignore-fixup-commits=false

ignore-fixup-amend-commits

Whether or not to ignore fixup=amend commits.

Default value	gitlint version	commandline flag	environment variable
true	>= 0.18.0	Not Available	Not Available

Examples

# CLI
gitlint -c general.ignore-fixup-amend-commits=false

#.gitlint
[general]
ignore-fixup-amend-commits=false

ignore-squash-commits

Whether or not to ignore squash commits.

Default value	gitlint version	commandline flag	environment variable
true	>= 0.9.0	Not Available	Not Available

Examples

# CLI
gitlint -c general.ignore-squash-commits=false

#.gitlint
[general]
ignore-squash-commits=false

21 KiB Raw Permalink Blame History

Configuration

The .gitlint file

Commandline config

Commit specific config

Configuration precedence

General Options

silent

Examples

verbosity

Examples

ignore

Examples

debug

Examples

target

Examples

config

Examples

extra-path

Examples

contrib

Examples

staged

Examples

fail-without-commits

Examples

regex-style-search

More context

Examples

ignore-stdin

Examples

ignore-merge-commits

Examples

ignore-revert-commits

Examples

ignore-fixup-commits

Examples

ignore-fixup-amend-commits

Examples

ignore-squash-commits

Examples

21 KiB

Raw Permalink Blame History