diff options
Diffstat (limited to 'docs/rules.md')
| -rw-r--r-- | docs/rules.md | 244 |
1 files changed, 204 insertions, 40 deletions
diff --git a/docs/rules.md b/docs/rules.md index 173c5b1..178f962 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -1,9 +1,12 @@ -# Overview # +# Overview -The table below shows an overview of all gitlint's built-in rules. -Note that you can also [write your own user-defined rule](user_defined_rules.md) in case you don't find +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. -The rest of this page contains details on the available configuration options for each built-in rule. + ID | Name | gitlint version | Description ------|-----------------------------|-------------------|------------------------------------------- @@ -13,7 +16,8 @@ T3 | title-trailing-punctuation | >= 0.1.0 | Title cannot have trai 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: .*) +T7 | title-match-regex | >= 0.5.0 | Title must match a given regex (default: None) +T8 | title-max-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) @@ -21,107 +25,181 @@ B4 | body-first-line-empty | >= 0.1.0 | First line of the body 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 | Title 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 + -## T1: title-max-length ## +## T1: title-max-length ID | Name | gitlint version | Description ------|-----------------------------|-----------------|------------------------------------------- T1 | title-max-length | >= 0.1 | Title length must be < 72 chars. -### Options ### +### Options Name | gitlint version | Default | Description ---------------|-----------------|---------|---------------------------------- line-length | >= 0.2 | 72 | Maximum allowed title length -## T2: title-trailing-whitespace ## +### 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 ## +## T3: title-trailing-punctuation ID | Name | gitlint version | Description ------|-----------------------------|-----------------|------------------------------------------- T3 | title-trailing-punctuation | >= 0.1 | Title cannot have trailing punctuation (?:!.,;) -## T4: title-hard-tab ## +## 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 ## +## 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 ### +### 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 -## T6: title-leading-whitespace ## +### 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 ## +## T7: title-match-regex ID | Name | gitlint version | Description ------|-----------------------------|-----------------|------------------------------------------- T7 | title-match-regex | >= 0.5 | Title must match a given regex (default: .*) -### Options ### +### Options Name | gitlint version | Default | Description ---------------|-----------------|---------|---------------------------------- -regex | >= 0.5 | .* | [Python-style regular expression](https://docs.python.org/3.5/library/re.html) that the title should match. +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]* +``` -## B1: body-max-line-length ## +## T8: title-min-length ## + +ID | Name | gitlint version | Description +------|-----------------------------|-----------------|------------------------------------------- +T1 | title-min-length | >= | 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 ### +### Options Name | gitlint version | Default | Description ---------------|-----------------|---------|---------------------------------- line-length | >= 0.2 | 80 | Maximum allowed line length in the commit message body -## B2: body-trailing-whitespace ## +### 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 ## +## 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 ## +## 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 ## +## B5: body-min-length ID | Name | gitlint version | Description ------|-----------------------------|-----------------|------------------------------------------- @@ -133,34 +211,83 @@ Name | gitlint version | Default | Description ---------------|-----------------|---------|---------------------------------- min-length | >= 0.4 | 20 | Minimum number of required characters in body -## B6: body-is-missing ## +### 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 ### +### 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 ## +## 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 ### +### 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 title should match. + +### Examples + +#### .gitlint + +```ini +# 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 ## +## M1: author-valid-email ID | Name | gitlint version | Description ------|-----------------------------|-----------------|------------------------------------------- @@ -172,30 +299,36 @@ M1 | author-valid-email | >= 0.8.3 | Author email address mus -### Options ### +### Options Name | gitlint version | Default | Description ----------------------|-------------------|------------------------------|---------------------------------- -regex | >= 0.9.0 | ```[^@ ]+@[^@ ]+\.[^@ ]+``` | Regex the commit author email address is matched against +regex | >= 0.9.0 | `[^@ ]+@[^@ ]+\.[^@ ]+` | [Python regex](https://docs.python.org/library/re.html) the commit author email address is matched against -!!! note - An often recurring use-case is to only allow email addresses from a certain domain. The following regular expression achieves this: ```[^@]+@foo.com``` +### Examples +#### .gitlint + +```ini +# Only allow email addresses from a foo.com domain +[author-valid-email] +regex=[^@]+@foo.com +``` -## I1: ignore-by-title ## +## 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 ### +### Options Name | gitlint version | Default | Description ----------------------|-------------------|------------------------------|---------------------------------- -regex | >= 0.10.0 | None | Regex to match against commit title. On match, the commit will be ignored. -ignore | >= 0.10.0 | all | Comma-seperated list of rule names or ids to ignore when this rule is matched. +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 @@ -211,19 +344,19 @@ ignore=title-max-length,body-min-length # ignore=all ``` -## I2: ignore-by-body ## +## 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 ### +### Options Name | gitlint version | Default | Description ----------------------|-------------------|------------------------------|---------------------------------- -regex | >= 0.10.0 | None | Regex to match against each line of the body. On match, the commit will be ignored. -ignore | >= 0.10.0 | all | Comma-seperated list of rule names or ids to ignore when this rule is matched. +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 @@ -240,4 +373,35 @@ ignore=all [ignore-by-body] regex=(.*)release(.*) ignore=T1,body-min-length,B6 -```
\ No newline at end of file +``` + +## 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(.*) +``` |