Built-in Rules

The page documents all of gitlint's built-in rules and their options.

All built-in rules are enabled by default. It's possible to ignore specific rules through configuration.

T1: title-max-length¶

v0.1.0 · ID: T1 · Name: title-max-length

Title length must be <= 72 chars.

Options¶

Name	Type	Default	gitlint version	Description
`line-length`	`int`	`72`	v0.2.0	Maximum allowed title length.

.gitlint

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

T2: title-trailing-whitespace¶

v0.1.0 · ID: T2 · Name: title-trailing-whitespace

Title cannot have trailing whitespace (space or tab).

T3: title-trailing-punctuation¶

v0.1.0 · ID: T3 · Name: title-trailing-punctuation

Title cannot have trailing punctuation (?:!.,;).

T4: title-hard-tab¶

v0.1.0 · ID: T4 · Name: title-hard-tab

Title cannot contain hard tab character (\t).

T5: title-must-not-contain-word¶

v0.1.0 · ID: T5 · Name: title-must-not-contain-word

Title cannot contain certain words.

Options¶

Name	Type	Default	gitlint version	Description
`words`	`str`	`"WIP"`	v0.3.0	Comma-separated list of words that should not be used in the title. Matching is case insensitive. Keywords occuring as part of a larger word are not matched (so `"WIPING"` is allowed).

.gitlint

# Ensure the title doesn't contain swear words
[title-must-not-contain-word]
words=crap,darn,damn

T6: title-leading-whitespace¶

v0.4.0 · ID: T6 · Name: title-leading-whitespace

Title cannot have leading whitespace (space or tab).

T7: title-match-regex¶

v0.5.0 · ID: T7 · Name: title-match-regex

Title must match a given regex (default: .*).

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`.*`	v0.5.0	Python regex the title should match.

.gitlint

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

T8: title-min-length¶

v0.14.0 · ID: T8 · Name: title-min-length

Title length must be >= 5 chars.

Options¶

Name	Type	Default	gitlint version	Description
`min-length`	`int`	`5`	v0.14.0	Minimum required title length

.gitlint

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

B1: body-max-line-length¶

v0.1.0 · ID: B1 · Name: body-max-line-length

Lines in the body must be <= 80 chars.

Options¶

Name	Type	Default	gitlint version	Description
`line-length`	`int`	`80`	v0.2.0	Maximum allowed line length in the commit message body.

.gitlint

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

B2: body-trailing-whitespace¶

v0.1.0 · ID: B2 · Name: body-trailing-whitespace

Body cannot have trailing whitespace (space or tab).

B3: body-hard-tab¶

v0.1.0 · ID: B3 · Name: body-hard-tab

Body cannot contain hard tab characters (\t).

B4: body-first-line-empty¶

v0.1.0 · ID: B4 · Name: body-first-line-empty

First line of the body (second line of commit message) must be empty.

B5: body-min-length¶

v0.4.0 · ID: B5 · Name: body-min-length

Body length must be at least 20 characters. Gitlint will not count newline characters towards this limit.

Options¶

Name	Type	Default	gitlint version	Description
`min-length`	`int`	`20`	v0.4.0	Minimum number of required characters in body.

.gitlint

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

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

B6: body-is-missing¶

v0.4.0 · ID: B6 · Name: body-is-missing

Body message must be specified.

Options¶

Name	Type	Default	gitlint version	Description
`ignore-merge-commits`	`bool`	`true`	v0.4.0	Whether this rule should be ignored during merge commits. Allowed values: true,false.

.gitlint

# You want gitlint to check enforce this rule for merge commits as well
[body-is-missing]
ignore-merge-commits=false

# This also needs to be enabled at the general gitlint level # (1)
[general]
ignore-merge-commits=false

By default, gitlint will ignore merge commits all-together.

B7: body-changed-file-mention¶

v0.4.0 · ID: B7 · Name: body-changed-file-mention

Body must contain references to certain files if those files are changed in the last commit.

Options¶

Name	Type	Default	gitlint version	Description
`files`	`str`	`empty`	v0.4.0	Comma-separated list of files that need to an explicit mention in the commit message in case they are changed.

.gitlint

# Prevent that certain files are committed by mistake by forcing
# users to mention them explicitly when they're deliberately changing them
[body-changed-file-mention]
files=generated.xml,secrets.txt,private-key.pem

B8: body-match-regex¶

v0.14.0 · ID: B8 · Name: body-match-regex

Body must match a given regex.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`empty`	v0.14.0	Python regex the body should match.

.gitlint

# 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(.*)

M1: author-valid-email¶

v0.9.0 · ID: M1 · Name: author-valid-email

Author email address must be a valid email address.

Note

Email addresses are notoriously hard to validate and the official email valid spec is often too loose for any real world application. Gitlint by default takes a pragmatic approach and requires users to enter email addresses that contain a name, domain and tld and has no spaces.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	[^@ ]+@[^@ ]+.[^@ ]+	v0.9.0	Python regex the commit author email address is matched against

.gitlint

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

I1: ignore-by-title¶

v0.10.0 · ID: I1 · Name: ignore-by-title

Ignore a commit based on matching its title.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`empty`	v0.10.0	Python regex to match against commit title. On match, the commit will be ignored.
`ignore`	`str`	`"all"`	v0.10.0	Comma-separated list of rule names or ids to ignore when this rule is matched.

.gitlint

# Match commit titles starting with Release
# For those commits, ignore title-max-length and body-min-length rules
[ignore-by-title]
regex=^Release(.*)
ignore=title-max-length,body-min-length,B6 # (1)

# Ignore all rules by setting ignore to 'all'
[ignore-by-title]
regex=^Release(.*)
ignore=all

You can use both names as well as ids to refer to other rules.

I2: ignore-by-body¶

v0.10.0 · ID: I2 · Name: ignore-by-body

Ignore a commit based on matching its body.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`empty`	v0.10.0	Python regex to match against commit body. On match, the commit will be ignored.
`ignore`	`str`	`"all"`	v0.10.0	Comma-separated list of rule names or ids to ignore when this rule is matched.

.gitlint

# Ignore all commits with a commit message body with a line that contains 'release'
# For matching commits, only ignore rules T1, body-min-length, B6.
[ignore-by-body]
regex=(.*)release(.*)
ignore=T1,body-min-length,B6 # (1)

# Ignore all rules by setting ignore to 'all'
[ignore-by-body]
regex=(.*)release(.*)
ignore=all

You can use both names as well as ids to refer to other rules.

I3: ignore-body-lines¶

v0.14.0 · ID: I3 · Name: ignore-body-lines

Ignore certain lines in a commit body that match a regex.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`empty`	v0.14.0	Python regex to match against each line of the body. On match, that line will be ignored by gitlint (the rest of the body will still be linted).

.gitlint

# Ignore all lines that start with 'Co-Authored-By'
[ignore-body-lines]
regex=^Co-Authored-By

# Ignore lines that start with 'Co-Authored-By' or with 'Signed-off-by'
[ignore-body-lines]
regex=(^Co-Authored-By)|(^Signed-off-by)

# Ignore lines that contain 'foobar'
[ignore-body-lines]
regex=(.*)foobar(.*)

I4: ignore-by-author-name¶

v0.16.0 · ID: I4 · Name: ignore-by-author-name

Ignore a commit based on matching its author name.

Options¶

Name	Type	Default	gitlint version	Description
`regex`	`str`	`empty`	v0.16.0	Python regex to match against the commit author name. On match, the commit will be ignored.
`ignore`	`str`	`"all"`	v0.16.0	Comma-separated list of rule names or ids to ignore when this rule is matched.

.gitlint

# Ignore all commits authored by dependabot
[ignore-by-author-name]
regex=dependabot

# For commits made by authors with "[bot]" in their name, ignore specific rules
[ignore-by-author-name]
regex=(.*)\[bot\](.*)
ignore=T1,body-min-length,B6 # (1)

You can use both names as well as ids to refer to other rules.