Adding upstream version 0.19.1.upstream/0.19.1upstream

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

1 files changed, 628 insertions, 0 deletions

diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..af49d7c
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,628 @@
+# Configuration
+Gitlint can be configured through different means.
+
+## 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:
+```sh
+gitlint generate-config
+```
+You can also use a different config file like so:
+
+```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
+[General Configuration](configuration.md#general-configuration) section of this page.
+
+```ini
+# Edit this file as you like.
+#
+# All these sections are optional. Each section with the exception of [general] represents
+# 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 also be written as "[B1]". Full section names are
+# used in here for clarity.
+# Rule reference documentation: http://jorisroovers.github.io/gitlint/rules/
+#
+# Use 'gitlint generate-config' to generate a config file with all possible options
+[general]
+# Ignore certain rules (comma-separated list), you can reference them by their
+# id or by their full name
+ignore=title-trailing-punctuation, T3
+
+# verbosity should be a value between 1 and 3, the commandline -v flags take
+# precedence over this
+verbosity = 2
+
+# By default gitlint will ignore merge, revert, fixup, fixup=amend, and squash commits.
+ignore-merge-commits=true
+ignore-revert-commits=true
+ignore-fixup-commits=true
+ignore-fixup-amend-commits=true
+ignore-squash-commits=true
+
+# Ignore any data sent to gitlint via stdin
+ignore-stdin=true
+
+# Fetch additional meta-data from the local repository when manually passing a
+# commit message to gitlint via stdin or --commit-msg. Disabled by default.
+staged=true
+
+# Hard fail when the target commit range is empty. Note that gitlint will
+# already fail by default on invalid commit ranges. This option is specifically
+# to tell gitlint to fail on *valid but empty* commit ranges.
+# Disabled by default.
+fail-without-commits=true
+
+# Whether to use Python `search` instead of `match` semantics in rules that use
+# regexes. Context: https://github.com/jorisroovers/gitlint/issues/254
+# Disabled by default, but will be enabled by default in the future.
+regex-style-search=true
+
+# Enable debug mode (prints more output). Disabled by default.
+debug=true
+
+# Enable community contributed rules
+# See http://jorisroovers.github.io/gitlint/contrib_rules for details
+contrib=contrib-title-conventional-commits,CC1
+
+# Set the extra-path where gitlint will search for user defined rules
+# See http://jorisroovers.github.io/gitlint/user_defined_rules for details
+extra-path=examples/
+
+# This is an example of how to configure the "title-max-length" rule and
+# set the line-length it enforces to 80
+[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"
+# will not cause a violation, but "WIP: my title" will.
+words=wip
+
+[title-match-regex]
+# python like regex (https://docs.python.org/3/library/re.html) that the
+# commit-msg title must be matched to.
+# Note that the regex can contradict with other rules if not used correctly
+# (e.g. title-must-not-contain-word).
+regex=^US[0-9]*
+
+[body-max-line-length]
+line-length=120
+
+[body-min-length]
+min-length=5
+
+[body-is-missing]
+# Whether to ignore this rule on merge commits (which typically only have a title)
+# default = True
+ignore-merge-commits=false
+
+[body-changed-file-mention]
+# List of files that need to be explicitly mentioned in the body when they are changed
+# This is useful for when developers often erroneously edit certain files or git submodules.
+# By specifying this rule, developers can only change the file when they explicitly
+# reference it in the commit message.
+files=gitlint-core/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/3/library/re.html) that the
+# commit author email address should be matched to
+# 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]
+# Ignore certain rules for commits of which the title matches a regex
+# E.g. Match commit titles that start with "Release"
+regex=^Release(.*)
+
+# Ignore certain rules, you can reference them by their id or by their full name
+# Use 'all' to ignore all rules
+ignore=T1,body-min-length
+
+[ignore-by-body]
+# Ignore certain rules for commits of which the body has a line that matches a regex
+# E.g. Match bodies that have a line that that contain "release"
+regex=(.*)release(.*)
+#
+# Ignore certain rules, you can reference them by their id or by their full name
+# 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
+
+[ignore-by-author-name]
+# Ignore certain rules for commits of which the author name matches a regex
+# E.g. Match commits made by dependabot
+regex=(.*)dependabot(.*)
+
+# Ignore certain rules, you can reference them by their id or by their full name
+# Use 'all' to ignore all rules
+ignore=T1,body-min-length
+
+# 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.
+[contrib-title-conventional-commits]
+# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
+types = bugfix,user-story,epic
+```
+
+## Commandline config
+
+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.
+
+## 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
+message like so:
+
+```
+WIP: This is my commit message
+
+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.
+
+You can also specify specific rules to be ignored as follows:
+```
+WIP: This is my commit message
+
+I want gitlint to ignore this entire commit message.
+gitlint-ignore: T1, body-hard-tab
+```
+
+
+
+## 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)
+2. Configuration Rules (e.g.: [ignore-by-title](rules.md#i1-ignore-by-title))
+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
+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.
+
+### silent
+
+Enable silent mode (no output). Use [exit](index.md#exit-codes) code to determine result.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| `False`       | >= 0.1.0        | `--silent`       | `GITLINT_SILENT`     |
+
+#### Examples
+```sh
+# CLI
+gitlint --silent
+GITLINT_SILENT=1 gitlint  # using env variable
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### verbosity
+
+Amount of output gitlint will show when printing errors.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| 3             | >= 0.1.0        | `-v`             | `GITLINT_VERBOSITY`  |
+
+
+#### Examples
+```sh
+# CLI
+gitlint -vvv                   # default     (level 3)
+gitlint -vv                    # less output (level 2)
+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
+[general]
+verbosity=2
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### ignore
+
+Comma separated list of rules to ignore (by name or id).
+
+| Default value    | gitlint version | commandline flag | environment variable |
+| ---------------- | --------------- | ---------------- | -------------------- |
+| [] (=empty list) | >= 0.1.0        | `--ignore`       | `GITLINT_IGNORE`     |
+
+#### 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_IGNORE=T1,body-min-length gitlint     # using env variable
+```
+```ini
+#.gitlint
+[general]
+ignore=T1,body-min-length
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### debug
+
+Enable debugging output.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| false         | >= 0.7.1        | `--debug`        | `GITLINT_DEBUG`      |
+
+#### Examples
+```sh
+# CLI
+gitlint --debug
+GITLINT_DEBUG=1 gitlint # using env variable
+# --debug is special, the following does NOT work
+# gitlint -c general.debug=true
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### target
+
+Target git repository gitlint should be linting against.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| (empty)       | >= 0.8.0        | `--target`       | `GITLINT_TARGET`     |
+
+#### Examples
+```sh
+# CLI
+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]
+target=/home/joe/myrepo/
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### config
+
+Path where gitlint looks for a config file.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| `.gitlint`    | >= 0.1.0        | `--config`       | `GITLINT_CONFIG`     |
+
+#### Examples
+```sh
+gitlint --config=/home/joe/gitlint.ini
+gitlint -C /home/joe/gitlint.ini      # different way of doing the same
+GITLINT_CONFIG=/home/joe/gitlint.ini  # using env variable
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### extra-path
+
+Path where gitlint looks for [user-defined rules](user_defined_rules.md).
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| (empty)       | >= 0.8.0        | `--extra-path`   | `GITLINT_EXTRA_PATH` |
+
+#### Examples
+```sh
+# CLI
+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]
+extra-path=/home/joe/rules/
+```
+------------------------------------------------------------------------------------------------------------------------
+### contrib
+
+Comma-separated list of [Contrib rules](contrib_rules.md) to enable (by name or id).
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| (empty)       | >= 0.12.0       | `--contrib`      | `GITLINT_CONTRIB`    |
+
+#### Examples
+```sh
+# CLI
+gitlint --contrib=contrib-title-conventional-commits,CC1
+# different way of doing the same
+gitlint -c general.contrib=contrib-title-conventional-commits,CC1
+# using env variable
+GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint
+```
+```ini
+#.gitlint
+[general]
+contrib=contrib-title-conventional-commits,CC1
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### staged
+
+Attempt smart guesses about meta info (like author name, email, branch, changed files, etc) when manually passing a
+commit message to gitlint via stdin or `--commit-msg`.
+
+Since in such cases no actual git commit exists (yet) for the message being linted, gitlint
+needs to apply some heuristics (like checking `git config` and any staged changes) to make a smart guess about what the
+likely author name, email, commit date, changed files and branch of the ensuing commit would be.
+
+When not using the `--staged` flag while linting a commit message via stdin or `--commit-msg`, gitlint will only have
+access to the commit message itself for linting and won't be able to enforce rules like
+[M1:author-valid-email](rules.md#m1-author-valid-email).
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| false         | >= 0.13.0       | `--staged`       | `GITLINT_STAGED`     |
+
+#### Examples
+```sh
+# CLI
+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
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### fail-without-commits
+
+Hard fail when the target commit range is empty. Note that gitlint will
+already fail by default on invalid commit ranges. This option is specifically
+to tell gitlint to fail on **valid but empty** commit ranges.
+
+| Default value | gitlint version | commandline flag         | environment variable           |
+| ------------- | --------------- | ------------------------ | ------------------------------ |
+| false         | >= 0.15.2       | `--fail-without-commits` | `GITLINT_FAIL_WITHOUT_COMMITS` |
+
+#### Examples
+```sh
+# CLI
+# The following will cause gitlint to hard fail (i.e. exit code > 0)
+# since HEAD..HEAD is a valid but empty commit range.
+gitlint --fail-without-commits --commits HEAD..HEAD
+GITLINT_FAIL_WITHOUT_COMMITS=1 gitlint       # using env variable
+```
+```ini
+#.gitlint
+[general]
+fail-without-commits=true
+```
+
+---
+### regex-style-search
+
+Whether to use Python `re.search()` instead of `re.match()` semantics in all built-in rules that use regular expressions. 
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| false         | >= 0.18.0       | Not Available    | Not Available        |
+
+!!! important
+    At this time, `regex-style-search` is **disabled** by default, but it will be **enabled** by default in the future.
+    
+
+
+Gitlint will log a warning when you're using a rule that uses a custom regex and this option is not enabled:
+
+```plain
+WARNING: I1 - ignore-by-title: gitlint will be switching from using Python regex 'match' (match beginning) to
+'search' (match anywhere) semantics. Please review your ignore-by-title.regex option accordingly.
+To remove this warning, set general.regex-style-search=True. 
+More details: https://jorisroovers.github.io/gitlint/configuration/#regex-style-search
+```
+
+*If you don't have any custom regex specified, gitlint will not log a warning and no action is needed.*
+
+**To remove the warning:** 
+
+1. Review your regex in the rules gitlint warned for and ensure it's still accurate when using [`re.search()` semantics](https://docs.python.org/3/library/re.html#search-vs-match).
+2. Enable `regex-style-search` in your `.gitlint` file (or using [any other way to configure gitlint](http://127.0.0.1:8000/gitlint/configuration/)):
+
+```ini
+[general]
+regex-style-search=true
+```
+
+#### More context
+Python offers [two different primitive operations based on regular expressions](https://docs.python.org/3/library/re.html#search-vs-match): 
+`re.match()` checks for a match only at the beginning of the string, while `re.search()` checks for a match anywhere
+in the string.
+
+
+
+Most rules in gitlint already use `re.search()` instead of `re.match()`, but there's a few notable exceptions that
+use `re.match()`, which can lead to unexpected matching behavior.
+
+- M1 - author-valid-email
+- I1 - ignore-by-title
+- I2 - ignore-by-body
+- I3 - ignore-body-lines
+- I4 - ignore-by-author-name
+
+The `regex-style-search` option is meant to fix this inconsistency. Setting it to `true` will force the above rules to
+use `re.search()` instead of `re.match()`. For detailed context, see [issue #254](https://github.com/jorisroovers/gitlint/issues/254).
+
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.regex-style-search=true
+```
+```ini
+#.gitlint
+[general]
+regex-style-search=true
+```
+------------------------------------------------------------------------------------------------------------------------
+### ignore-stdin
+
+Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
+
+| Default value | gitlint version | commandline flag | environment variable   |
+| ------------- | --------------- | ---------------- | ---------------------- |
+| false         | >= 0.12.0       | `--ignore-stdin` | `GITLINT_IGNORE_STDIN` |
+
+#### Examples
+```sh
+# CLI
+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]
+ignore-stdin=true
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### ignore-merge-commits
+
+Whether or not to ignore merge commits.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| true          | >= 0.7.0        | Not Available    | Not Available        |
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-merge-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-merge-commits=false
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### ignore-revert-commits
+
+Whether or not to ignore revert commits.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| true          | >= 0.13.0       | Not Available    | Not Available        |
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-revert-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-revert-commits=false
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### 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 | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| true          | >= 0.9.0        | Not Available    | Not Available        |
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-fixup-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-fixup-commits=false
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### ignore-fixup-amend-commits
+
+Whether or not to ignore [fixup=amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt) commits.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| true          | >= 0.18.0       | Not Available    | Not Available        |
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-fixup-amend-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-fixup-amend-commits=false
+```
+------------------------------------------------------------------------------------------------------------------------
+
+### ignore-squash-commits
+
+Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits.
+
+| Default value | gitlint version | commandline flag | environment variable |
+| ------------- | --------------- | ---------------- | -------------------- |
+| true          | >= 0.9.0        | Not Available    | Not Available        |
+
+#### Examples
+```sh
+# CLI
+gitlint -c general.ignore-squash-commits=false
+```
+```ini
+#.gitlint
+[general]
+ignore-squash-commits=false
+```
\ No newline at end of file