# 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 **contrib**uted rules](contrib_rules.md) which are not listed here as they're disabled by default. In addition, you can also [write your own user-defined rule](user_defined_rules.md) 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 ```ini # 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 ```ini # 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](https://docs.python.org/library/re.html) that the title should match. | ### Examples #### .gitlint ```ini # 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 ```ini # 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 ```ini # 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 ```ini # 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 ```ini # 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](https://docs.python.org/library/re.html) that the body should match. | ### Examples #### .gitlint ```ini # Ensure the body ends with Reviewed-By: [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](http://stackoverflow.com/a/201378/381010). 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](https://docs.python.org/library/re.html) the commit author email address is matched against | ### Examples #### .gitlint ```ini # 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](https://docs.python.org/library/re.html) 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 ```ini # 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](https://docs.python.org/library/re.html) 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 ```ini # 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](https://docs.python.org/library/re.html) 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 ```ini # 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](https://docs.python.org/library/re.html) 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 ```ini # 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 ```