Adding upstream version 0.19.1.upstream/0.19.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 461 insertions, 0 deletions

diff --git a/docs/rules.md b/docs/rules.md
new file mode 100644
index 0000000..a992f26
--- /dev/null
+++ b/docs/rules.md
@@ -0,0 +1,461 @@
+# 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: <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                                        |
+| --- | ------------------ | --------------- | -------------------------------------------------- |
+| 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
+```