diff options
Diffstat (limited to 'docs/rules.md')
| -rw-r--r-- | docs/rules.md | 287 |
1 files changed, 155 insertions, 132 deletions
diff --git a/docs/rules.md b/docs/rules.md index eb4b65e..a992f26 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -8,43 +8,43 @@ In addition, you can also [write your own user-defined rule](user_defined_rules. 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 | 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 -I4 | ignore-by-author-name | >= 0.16.0 | Ignore a commit based on matching its author name +| 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. +| 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 +| Name | gitlint version | Default | Description | +| ----------- | --------------- | ------- | ---------------------------- | +| line-length | >= 0.2 | 72 | Maximum allowed title length | ### Examples @@ -59,39 +59,43 @@ line-length=72 [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) +| 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 (?:!.,;) +| 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) +| 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") +| 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 +| 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 @@ -102,25 +106,28 @@ words | >= 0.3 | WIP | Comma-separated list of words that [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) +| 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: .*) +| 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. +| Name | gitlint version | Default | Description | +| ----- | --------------- | ------- | ------------------------------------------------------------------------------------ | +| regex | >= 0.5 | .* | [Python regex](https://docs.python.org/library/re.html) that the title should match. | ### Examples @@ -131,19 +138,20 @@ regex | >= 0.5 | .* | [Python regex](https://docs.python. [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. +| 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 +| Name | gitlint version | Default | Description | +| ---------- | --------------- | ------- | ----------------------------- | +| min-length | >= 0.14.0 | 5 | Minimum required title length | ### Examples @@ -154,18 +162,19 @@ min-length | >= 0.14.0 | 5 | Minimum required title length [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 +| 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 +| Name | gitlint version | Default | Description | +| ----------- | --------------- | ------- | ------------------------------------------------------ | +| line-length | >= 0.2 | 80 | Maximum allowed line length in the commit message body | ### Examples @@ -180,38 +189,43 @@ line-length=120 [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) +| 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) +| 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 +| 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. +| 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 +| Name | gitlint version | Default | Description | +| ---------- | --------------- | ------- | --------------------------------------------- | +| min-length | >= 0.4 | 20 | Minimum number of required characters in body | ### Examples @@ -226,31 +240,34 @@ min-length=5 [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 +| 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. +| 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 +| 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. +| 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 @@ -262,18 +279,19 @@ files | >= 0.4 | (empty) | Comma-separated list o [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 +| 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. +| Name | gitlint version | Default | Description | +| ----- | --------------- | ------- | ----------------------------------------------------------------------------------- | +| regex | >= 0.14 | None | [Python regex](https://docs.python.org/library/re.html) that the body should match. | ### Examples @@ -288,12 +306,13 @@ regex=Reviewed-By:(.*)$ [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 +| 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). @@ -303,9 +322,9 @@ M1 | author-valid-email | >= 0.8.3 | Author email address mus ### 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 +| 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 @@ -317,20 +336,21 @@ regex | >= 0.9.0 | `[^@ ]+@[^@ ]+\.[^@ ]+` | [Python [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. +| 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. +| 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 @@ -345,20 +365,21 @@ 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. +| 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. +| 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 @@ -376,19 +397,20 @@ ignore=all 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. +| 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). +| 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 @@ -407,19 +429,20 @@ regex=(^Co-Authored-By)|(^Signed-off-by) [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. +| 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. +| 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 @@ -435,4 +458,4 @@ regex=dependabot [ignore-by-author-name] regex=(.*)\[bot\](.*) ignore=T1,body-min-length,B6 -```
\ No newline at end of file +``` |