Adding upstream version 0.14.0.upstream/0.14.0

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

1 files changed, 161 insertions, 135 deletions

diff --git a/docs/configuration.md b/docs/configuration.md
index 641b361..78224c1 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,21 +1,21 @@
 # Configuration
 Gitlint can be configured through different means.
 
-# Config files #
-You can modify gitlint's behavior by adding a ```.gitlint``` file to your git repository.
+## The .gitlint file
+You can modify gitlint's behavior by adding a `.gitlint` file to your git repository.
 
-Generate a default ```.gitlint``` config file by running:
-```bash
+Generate a default `.gitlint` config file by running:
+```sh
 gitlint generate-config
 ```
 You can also use a different config file like so:
 
-```bash
+```sh
 gitlint --config myconfigfile.ini 
 ```
 
-The block below shows a sample ```.gitlint``` file. Details about rule config options can be found on the
-[Rules](rules.md) page, details about the ```[general]``` section can be found in the
+The block below shows a sample `.gitlint` file. Details about rule config options can be found on the
+[Rules](rules.md) page, details about the `[general]` section can be found in the
 [General Configuration](configuration.md#general-configuration) section of this page.
 
 ```ini
@@ -25,7 +25,7 @@ The block below shows a sample ```.gitlint``` file. Details about rule config op
 # one rule and each key in it is an option for that specific rule.
 #
 # Rules and sections can be referenced by their full name or by id. For example
-# section "[body-max-line-length]" could be written as "[B1]". Full section names are
+# section "[body-max-line-length]" could also be written as "[B1]". Full section names are
 # used in here for clarity.
 # Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/
 #
@@ -68,6 +68,11 @@ extra-path=examples/
 [title-max-length]
 line-length=80
 
+# Conversely, you can also enforce minimal length of a title with the
+# "title-min-length" rule:
+[title-min-length]
+min-length=5
+
 [title-must-not-contain-word]
 # Comma-separated list of words that should not occur in the title. Matching is case
 # insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING"
@@ -99,10 +104,15 @@ ignore-merge-commits=false
 # it in the commit message.
 files=gitlint/rules.py,README.md
 
+[body-match-regex]
+# python-style regex that the commit-msg body must match.
+# E.g. body must end in My-Commit-Tag: foo
+regex=My-Commit-Tag: foo$
+
 [author-valid-email]
 # python like regex (https://docs.python.org/2/library/re.html) that the
 # commit author email address should be matched to
-# For example, use the following regex if you only want to allow email addresses from foo.com
+# E.g.: For example, use the following regex if you only want to allow email addresses from foo.com
 regex=[^@]+@foo.com
 
 [ignore-by-title]
@@ -123,6 +133,11 @@ ignore=T1,body-min-length
 # Use 'all' to ignore all rules
 ignore=T1,body-min-length
 
+[ignore-body-lines]
+# Ignore certain lines in a commit body that match a regex.
+# E.g. Ignore all lines that start with 'Co-Authored-By'
+regex=^Co-Authored-By
+
 # This is a contrib rule - a community contributed rule. These are disabled by default.
 # You need to explicitly enable them one-by-one by adding them to the "contrib" option
 # under [general] section above.
@@ -131,20 +146,20 @@ ignore=T1,body-min-length
 types = bugfix,user-story,epic
 ```
 
-# Commandline config #
+## Commandline config
 
-You can also use one or more ```-c``` flags like so:
+You can also use one or more `-c` flags like so:
 
 ```
 $ gitlint -c general.verbosity=2 -c title-max-length.line-length=80 -c B1.line-length=100
 ```
-The generic config flag format is ```-c <rule>.<option>=<value>``` and supports all the same rules and options which
-you can also use in a ```.gitlint``` config file.
+The generic config flag format is `-c <rule>.<option>=<value>` and supports all the same rules and options which
+you can also use in a `.gitlint` config file.
 
-# Commit specific config #
+## Commit specific config
 
 You can also configure gitlint by adding specific lines to your commit message.
-For now, we only support ignoring commits by adding ```gitlint-ignore: all``` to the commit
+For now, we only support ignoring commits by adding `gitlint-ignore: all` to the commit
 message like so:
 
 ```
@@ -154,7 +169,7 @@ I want gitlint to ignore this entire commit message.
 gitlint-ignore: all
 ```
 
-```gitlint-ignore: all``` can occur on any line, as long as it is at the start of the line.
+`gitlint-ignore: all` can occur on any line, as long as it is at the start of the line.
 
 You can also specify specific rules to be ignored as follows: 
 ```
@@ -166,44 +181,46 @@ gitlint-ignore: T1, body-hard-tab
 
 
 
-# Configuration precedence #
+## Configuration precedence
 gitlint configuration is applied in the following order of precedence:
 
-1. Commit specific config (e.g.: ```gitlint-ignore: all``` in the commit message)
+1. Commit specific config (e.g.: `gitlint-ignore: all` in the commit message)
 2. Configuration Rules (e.g.: [ignore-by-title](/rules/#i1-ignore-by-title))
-3. Commandline convenience flags (e.g.:  ```-vv```, ```--silent```, ```--ignore```)
-4. Commandline configuration flags (e.g.: ```-c title-max-length=123```)
-5. Configuration file (local ```.gitlint``` file, or file specified using ```-C```/```--config```)
-6. Default gitlint config
+3. Commandline convenience flags (e.g.:  `-vv`, `--silent`, `--ignore`)
+4. Environment variables (e.g.: `GITLINT_VERBOSITY=3`)
+5. Commandline configuration flags (e.g.: `-c title-max-length=123`)
+6. Configuration file (local `.gitlint` file, or file specified using `-C`/`--config`)
+7. Default gitlint config
 
-# General Options
+## General Options
 Below we outline all configuration options that modify gitlint's overall behavior. These options can be specified
-using commandline flags or in ```[general]``` section in a ```.gitlint``` configuration file.
+using commandline flags or in `[general]` section in a `.gitlint` configuration file.
 
-## silent
+### silent
 
 Enable silent mode (no output). Use [exit](index.md#exit-codes) code to determine result.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- false         | >= 0.1.0         | ```--silent```
+Default value  |  gitlint version | commandline flag  | environment variable
+---------------|------------------|-------------------|-----------------------
+`False`        | >= 0.1.0         | `--silent`        | `GITLINT_SILENT`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --silent
+GITLINT_SILENT=1 gitlint  # using env variable
 ```
 
-## verbosity
+### verbosity
 
 Amount of output gitlint will show when printing errors.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- 3             | >= 0.1.0         | `-v`
+Default value  |  gitlint version | commandline flag  | environment variable 
+---------------|------------------|-------------------|-----------------------
+3              | >= 0.1.0         | `-v`              | `GITLINT_VERBOSITY`
 
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -vvv                   # default     (level 3)
@@ -212,221 +229,230 @@ gitlint -v                     # even less   (level 1)
 gitlint --silent               # no output   (level 0)
 gitlint -c general.verbosity=1 # Set specific level
 gitlint -c general.verbosity=0 # Same as --silent
+GITLINT_VERBOSITY=2 gitlint    # using env variable
 ```
 ```ini
-.gitlint
+# .gitlint
 [general]
 verbosity=2
 ```
 
-## ignore-merge-commits
+### ignore
 
-Whether or not to ignore merge commits.
+Comma separated list of rules to ignore (by name or id).
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- true          | >= 0.7.0         | Not Available
+Default value              |  gitlint version | commandline flag  | environment variable   
+---------------------------|------------------|-------------------|-----------------------
+ [] (=empty list)          | >= 0.1.0         | `--ignore`        | `GITLINT_IGNORE`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint -c general.ignore-merge-commits=false
+gitlint --ignore=body-min-length              # ignore single rule
+gitlint --ignore=T1,body-min-length           # ignore multiple rule
+gitlint -c general.ignore=T1,body-min-length  # different way of doing the same
+GITLINT_IGNORE=T1,body-min-length gitlint     # using env variable
 ```
 ```ini
 #.gitlint
 [general]
-ignore-merge-commits=false
+ignore=T1,body-min-length
 ```
 
-## ignore-revert-commits
+### debug
 
-Whether or not to ignore revert commits.
+Enable debugging output.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- true          | >= 0.13.0        | Not Available
+Default value  |  gitlint version | commandline flag  | environment variable   
+---------------|------------------|-------------------|-----------------------
+ false         | >= 0.7.1         | `--debug`         | `GITLINT_DEBUG`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint -c general.ignore-revert-commits=false
-```
-```ini
-#.gitlint
-[general]
-ignore-revert-commits=false
+gitlint --debug
+GITLINT_DEBUG=1 gitlint # using env variable
+# --debug is special, the following does NOT work
+# gitlint -c general.debug=true
 ```
 
-## ignore-fixup-commits
+### target
 
-Whether or not to ignore [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits.
+Target git repository gitlint should be linting against.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- true          | >= 0.9.0         | Not Available
+Default value              |  gitlint version | commandline flag  | environment variable   
+---------------------------|------------------|-------------------|-----------------------
+(empty)                    | >= 0.8.0         | `--target`        | `GITLINT_TARGET`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint -c general.ignore-fixup-commits=false
+gitlint --target=/home/joe/myrepo/
+gitlint -c general.target=/home/joe/myrepo/  # different way of doing the same
+GITLINT_TARGET=/home/joe/myrepo/ gitlint     # using env variable
 ```
 ```ini
 #.gitlint
 [general]
-ignore-fixup-commits=false
+target=/home/joe/myrepo/
 ```
 
-## ignore-squash-commits
+### extra-path
 
-Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits.
+Path where gitlint looks for [user-defined rules](user_defined_rules.md).
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- true          | >= 0.9.0         | Not Available
+Default value              |  gitlint version | commandline flag  | environment variable   
+---------------------------|------------------|-------------------|-----------------------
+ (empty)                   | >= 0.8.0         | `--extra-path`    | `GITLINT_EXTRA_PATH`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint -c general.ignore-squash-commits=false
+gitlint --extra-path=/home/joe/rules/
+gitlint -c general.extra-path=/home/joe/rules/  # different way of doing the same
+GITLINT_EXTRA_PATH=/home/joe/rules/ gitlint     # using env variable
 ```
 ```ini
 #.gitlint
 [general]
-ignore-squash-commits=false
+extra-path=/home/joe/rules/
 ```
 
-## ignore
+### contrib
 
-Comma separated list of rules to ignore (by name or id).
+Comma-separated list of [Contrib rules](contrib_rules) to enable (by name or id).
 
-Default value              |  gitlint version | commandline flag  
----------------------------|------------------|-------------------
- [] (=empty list)          | >= 0.1.0         | `--ignore`
+Default value              |  gitlint version | commandline flag  | environment variable   
+---------------------------|------------------|-------------------|-----------------------
+ (empty)                   | >= 0.12.0        | `--contrib`       | `GITLINT_CONTRIB`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --ignore=body-min-length              # ignore single rule
-gitlint --ignore=T1,body-min-length           # ignore multiple rule
-gitlint -c general.ignore=T1,body-min-length  # different way of doing the same
+gitlint --contrib=contrib-title-conventional-commits,CC1
+gitlint -c general.contrib=contrib-title-conventional-commits,CC1  # different way of doing the same
+GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint     # using env variable
 ```
 ```ini
 #.gitlint
 [general]
-ignore=T1,body-min-length
+contrib=contrib-title-conventional-commits,CC1
 ```
 
-## debug
+### staged
 
-Enable debugging output.
+Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or `--commit-msg`.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- false         | >= 0.7.1         | `--debug`
+Default value  |  gitlint version | commandline flag  | environment variable   
+---------------|------------------|-------------------|-----------------------
+ false         | >= 0.13.0        | `--staged`        | `GITLINT_STAGED`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --debug
-# --debug is special, the following does NOT work
-# gitlint -c general.debug=true
+gitlint --staged
+gitlint -c general.staged=true # different way of doing the same
+GITLINT_STAGED=1 gitlint       # using env variable
+```
+```ini
+#.gitlint
+[general]
+staged=true
 ```
 
-## target
+### ignore-stdin
 
-Target git repository gitlint should be linting against.
+Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
 
-Default value              |  gitlint version | commandline flag  
----------------------------|------------------|-------------------
- (empty)                   | >= 0.8.0         | `--target`
+Default value  |  gitlint version | commandline flag  | environment variable   
+---------------|------------------|-------------------|-----------------------
+ false         | >= 0.12.0        | `--ignore-stdin`  | `GITLINT_IGNORE_STDIN`
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --target=/home/joe/myrepo/
-gitlint -c general.target=/home/joe/myrepo/  # different way of doing the same
+gitlint --ignore-stdin
+gitlint -c general.ignore-stdin=true # different way of doing the same
+GITLINT_IGNORE_STDIN=1 gitlint       # using env variable
 ```
 ```ini
 #.gitlint
 [general]
-target=/home/joe/myrepo/
+ignore-stdin=true
 ```
 
-## extra-path
+### ignore-merge-commits
 
-Path where gitlint looks for [user-defined rules](user_defined_rules.md).
+Whether or not to ignore merge commits.
 
-Default value              |  gitlint version | commandline flag  
----------------------------|------------------|-------------------
- (empty)                   | >= 0.8.0         | `--extra-path`
+Default value  |  gitlint version | commandline flag  | environment variable  
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.7.0         | Not Available     | Not Available  
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --extra-path=/home/joe/rules/
-gitlint -c general.extra-path=/home/joe/rules/  # different way of doing the same
+gitlint -c general.ignore-merge-commits=false
 ```
 ```ini
 #.gitlint
 [general]
-extra-path=/home/joe/rules/
+ignore-merge-commits=false
 ```
 
-## contrib
+### ignore-revert-commits
 
-[Contrib rules](contrib_rules) to enable.
+Whether or not to ignore revert commits.
 
-Default value              |  gitlint version | commandline flag  
----------------------------|------------------|-------------------
- (empty)                   | >= 0.12.0        | `--contrib`
+Default value  |  gitlint version | commandline flag  | environment variable   
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.13.0        | Not Available     | Not Available  
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --contrib=contrib-title-conventional-commits,CC1
-gitlint -c general.contrib=contrib-title-conventional-commits,CC1  # different way of doing the same
+gitlint -c general.ignore-revert-commits=false
 ```
 ```ini
 #.gitlint
 [general]
-contrib=contrib-title-conventional-commits,CC1
+ignore-revert-commits=false
 ```
-## ignore-stdin
 
-Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
+### ignore-fixup-commits
+
+Whether or not to ignore [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- false         | >= 0.12.0        | `--ignore-stdin`
+Default value  |  gitlint version | commandline flag  | environment variable  
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.9.0         | Not Available     | Not Available  
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --ignore-stdin
-gitlint -c general.ignore-stdin=true # different way of doing the same
+gitlint -c general.ignore-fixup-commits=false
 ```
 ```ini
 #.gitlint
 [general]
-ignore-stdin=true
+ignore-fixup-commits=false
 ```
 
-## staged
+### ignore-squash-commits
 
-Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or ```--commit-msg```.
+Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits.
 
-Default value  |  gitlint version | commandline flag  
----------------|------------------|-------------------
- false         | >= 0.13.0        | `--staged`
+Default value  |  gitlint version | commandline flag  | environment variable 
+---------------|------------------|-------------------|-----------------------
+ true          | >= 0.9.0         | Not Available     | Not Available  
 
-### Examples
+#### Examples
 ```sh
 # CLI
-gitlint --staged
-gitlint -c general.staged=true # different way of doing the same
+gitlint -c general.ignore-squash-commits=false
 ```
 ```ini
 #.gitlint
 [general]
-staged=true
+ignore-squash-commits=false
 ```
\ No newline at end of file