1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
# 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
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
------|-----------------------------|-------------------|-------------------------------------------
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: .*)
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
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
## 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
## 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
## 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-style regular expression](https://docs.python.org/3.5/library/re.html) that the title should match.
## 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
## 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
## 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.
## 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 | ```[^@ ]+@[^@ ]+\.[^@ ]+``` | Regex 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```
## 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 | 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.
### 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 | 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.
### 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
```
|
