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
