Merging upstream version 0.14.0.
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
parent
4c68f51a53
commit
e916bee311
GPG key ID:
FBB4F0E80A80222F
109 changed files with 2822 additions and 912 deletions
244
docs/rules.md
244
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.
|
||||
|
||||
## B1: body-max-line-length ##
|
||||
### 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
|
||||
------|-----------------------------|-----------------|-------------------------------------------
|
||||
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
|
||||
|
||||
## M1: author-valid-email ##
|
||||
```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
|
||||
|
||||
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
|
||||
|
||||
## I1: ignore-by-title ##
|
||||
```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 ###
|
||||
### 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
|
||||
```
|
||||
```
|
||||
|
||||
## 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(.*)
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue