Overview

The table below shows an overview of all gitlint's built-in rules, with more specific details further down the page.

Gitlint also has community contributed rules which are not listed here as they're disabled by default.

In addition, you can also write your own user-defined rule in case you don't find what you're looking for.

ID Name gitlint version Description
T1 title-max-length >= 0.1.0 Title length must be < 72 chars.
T2 title-trailing-whitespace >= 0.1.0 Title cannot have trailing whitespace (space or tab)
T3 title-trailing-punctuation >= 0.1.0 Title cannot have trailing punctuation (?:!.,;)
T4 title-hard-tab >= 0.1.0 Title cannot contain hard tab characters (\t)
T5 title-must-not-contain-word >= 0.1.0 Title cannot contain certain words (default: "WIP")
T6 title-leading-whitespace >= 0.4.0 Title cannot have leading whitespace (space or tab)
T7 title-match-regex >= 0.5.0 Title must match a given regex (default: None)
T8 title-min-length >= 0.14.0 Title length must be > 5 chars.
B1 body-max-line-length >= 0.1.0 Lines in the body must be < 80 chars
B2 body-trailing-whitespace >= 0.1.0 Body cannot have trailing whitespace (space or tab)
B3 body-hard-tab >= 0.1.0 Body cannot contain hard tab characters (\t)
B4 body-first-line-empty >= 0.1.0 First line of the body (second line of commit message) must be empty
B5 body-min-length >= 0.4.0 Body length must be at least 20 characters
B6 body-is-missing >= 0.4.0 Body message must be specified
B7 body-changed-file-mention >= 0.4.0 Body must contain references to certain files if those files are changed in the last commit
B8 body-match-regex >= 0.14.0 Body must match a given regex (default: None)
M1 author-valid-email >= 0.9.0 Author email address must be a valid email address
I1 ignore-by-title >= 0.10.0 Ignore a commit based on matching its title
I2 ignore-by-body >= 0.10.0 Ignore a commit based on matching its body
I3 ignore-body-lines >= 0.14.0 Ignore certain lines in a commit body that match a regex
I4 ignore-by-author-name >= 0.16.0 Ignore a commit based on matching its author name

T1: title-max-length

ID Name gitlint version Description
T1 title-max-length >= 0.1 Title length must be < 72 chars.

Options

Name gitlint version Default Description
line-length >= 0.2 72 Maximum allowed title length

Examples

.gitlint

# Titles should be max 72 chars
[title-max-length]
line-length=72

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

T2: title-trailing-whitespace

ID Name gitlint version Description
T2 title-trailing-whitespace >= 0.1 Title cannot have trailing whitespace (space or tab)

T3: title-trailing-punctuation

ID Name gitlint version Description
T3 title-trailing-punctuation >= 0.1 Title cannot have trailing punctuation (?:!.,;)

T4: title-hard-tab

ID Name gitlint version Description
T4 title-hard-tab >= 0.1 Title cannot contain hard tab characters (\t)

T5: title-must-not-contain-word

ID Name gitlint version Description
T5 title-must-not-contain-word >= 0.1 Title cannot contain certain words (default: "WIP")

Options

Name gitlint version Default Description
words >= 0.3 WIP Comma-separated list of words that should not be used in the title. Matching is case insensitive

Examples

.gitlint

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

T6: title-leading-whitespace

ID Name gitlint version Description
T6 title-leading-whitespace >= 0.4 Title cannot have leading whitespace (space or tab)

T7: title-match-regex

ID Name gitlint version Description
T7 title-match-regex >= 0.5 Title must match a given regex (default: .*)

Options

Name gitlint version Default Description
regex >= 0.5 .* Python regex that the title should match.

Examples

.gitlint

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

T8: title-min-length

ID Name gitlint version Description
T8 title-min-length >= 0.14.0 Title length must be > 5 chars.

Options

Name gitlint version Default Description
min-length >= 0.14.0 5 Minimum required title length

Examples

.gitlint

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

B1: body-max-line-length

ID Name gitlint version Description
B1 body-max-line-length >= 0.1 Lines in the body must be < 80 chars

Options

Name gitlint version Default Description
line-length >= 0.2 80 Maximum allowed line length in the commit message body

Examples

.gitlint

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

# Your tool prefers 72
[body-max-line-length]
line-length=72

B2: body-trailing-whitespace

ID Name gitlint version Description
B2 body-trailing-whitespace >= 0.1 Body cannot have trailing whitespace (space or tab)

B3: body-hard-tab

ID Name gitlint version Description
B3 body-hard-tab >= 0.1 Body cannot contain hard tab characters (\t)

B4: body-first-line-empty

ID Name gitlint version Description
B4 body-first-line-empty >= 0.1 First line of the body (second line of commit message) must be empty

B5: body-min-length

ID Name gitlint version Description
B5 body-min-length >= 0.4 Body length must be at least 20 characters. In versions >= 0.8.0, gitlint will not count newline characters.

Options

Name gitlint version Default Description
min-length >= 0.4 20 Minimum number of required characters in body

Examples

.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

ID Name gitlint version Description
B6 body-is-missing >= 0.4 Body message must be specified

Options

Name gitlint version Default Description
ignore-merge-commits >= 0.4 true Whether this rule should be ignored during merge commits. Allowed values: true,false.

B7: body-changed-file-mention

ID Name gitlint version Description
B7 body-changed-file-mention >= 0.4 Body must contain references to certain files if those files are changed in the last commit

Options

Name gitlint version Default Description
files >= 0.4 (empty) Comma-separated list of files that need to an explicit mention in the commit message in case they are changed.

Examples

.gitlint

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

B8: body-match-regex

ID Name gitlint version Description
B8 body-match-regex >= 0.14 Body must match a given regex

Options

Name gitlint version Default Description
regex >= 0.14 None Python regex that the body should match.

Examples

.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

ID Name gitlint version Description
M1 author-valid-email >= 0.8.3 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 gitlint version Default Description
regex >= 0.9.0 [^@ ]+@[^@ ]+\.[^@ ]+ Python regex the commit author email address is matched against

Examples

.gitlint

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

I1: ignore-by-title

ID Name gitlint version Description
I1 ignore-by-title >= 0.10.0 Ignore a commit based on matching its title.

Options

Name gitlint version Default Description
regex >= 0.10.0 None Python regex to match against commit title. On match, the commit will be ignored.
ignore >= 0.10.0 all Comma-separated list of rule names or ids to ignore when this rule is matched.

Examples

.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
# ignore all rules by setting ignore to 'all'
# ignore=all

I2: ignore-by-body

ID Name gitlint version Description
I2 ignore-by-body >= 0.10.0 Ignore a commit based on matching its body.

Options

Name gitlint version Default Description
regex >= 0.10.0 None Python regex to match against each line of the body. On match, the commit will be ignored.
ignore >= 0.10.0 all Comma-separated list of rule names or ids to ignore when this rule is matched.

Examples

.gitlint

# Ignore all commits with a commit message body with a line that contains 'release'
[ignore-by-body]
regex=(.*)release(.*)
ignore=all

# For matching commits, only ignore rules T1, body-min-length, B6.
# You can use both names as well as ids to refer to other rules.
[ignore-by-body]
regex=(.*)release(.*)
ignore=T1,body-min-length,B6

I3: ignore-body-lines

ID Name gitlint version Description
I3 ignore-body-lines >= 0.14.0 Ignore certain lines in a commit body that match a regex.

Options

Name gitlint version Default Description
regex >= 0.14.0 None 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).

Examples

.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

ID Name gitlint version Description
I4 ignore-by-author-name >= 0.16.0 Ignore a commit based on matching its author name.

Options

Name gitlint version Default Description
regex >= 0.16.0 None Python regex to match against the commit author name. On match, the commit will be ignored.
ignore >= 0.16.0 all Comma-separated list of rule names or ids to ignore when this rule is matched.

Examples

.gitlint

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

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