Material for Mkdocs (#489)

- Switches mkdocs theme from read-the-docs to Material for Mkdocs
- Review and rewrite of all documentation pages

47 files changed, 2997 insertions, 2389 deletions

diff --git a/docs/alternatives.md b/docs/alternatives.md
new file mode 100644
index 0000000..749f889
--- /dev/null
+++ b/docs/alternatives.md
@@ -0,0 +1,7 @@
+gitlint is not the only git commit message linter out there.
+
+Here's a few alternatives:
+
+- [commitlint](http://marionebl.github.io/commitlint) (Node.js)
+- [fit-commit](https://github.com/m1foley/fit-commit) (Ruby)
+- [node-commit-msg](https://github.com/clns/node-commit-msg) (Node.js)
diff --git a/docs/ci.md b/docs/ci.md
new file mode 100644
index 0000000..30a50ac
--- /dev/null
+++ b/docs/ci.md
@@ -0,0 +1,21 @@
+# Using gitlint in a CI environment
+By default, when just running `gitlint` without additional parameters, gitlint lints the last commit in the current
+working directory.
+
+This makes it easy to use gitlint in a CI environment (Jenkins, TravisCI, Github Actions, pre-commit, CircleCI, Gitlab, etc).
+In fact, this is exactly what we do ourselves: on every commit,
+[we run gitlint as part of our CI checks](https://github.com/jorisroovers/gitlint/blob/2a77afd845832c1a00a65e210f9339344dd6f114/.github/workflows/ci.yml#L90-L92).
+This will cause the build to fail when we submit a bad commit message.
+
+Alternatively, gitlint will also lint any commit message that you feed it via stdin like so:
+```sh
+# lint the last commit message
+git log -1 --pretty=%B | gitlint # (1)
+# lint a specific commit: 62c0519
+git log -1 --pretty=%B 62c0519 | gitlint
+```
+
+1. Gitlint requires that you specify `--pretty=%B` (=only print the log message, not the metadata),
+   future versions of gitlint might fix this and not require the `--pretty` argument.
+
+It's also possible to [lint more than one commit at once](linting_specific_commits.md).
\ No newline at end of file
diff --git a/docs/commit_hooks.md b/docs/commit_hooks.md
new file mode 100644
index 0000000..b43050f
--- /dev/null
+++ b/docs/commit_hooks.md
@@ -0,0 +1,91 @@
+## Commit-msg hook
+[:octicons-tag-24: v0.4.0][v0.4.0]
+
+You can install gitlint as a git `commit-msg` hook so that gitlint checks your commit messages automatically
+after each commit.
+
+```sh
+gitlint install-hook
+
+# Remove the hook
+gitlint uninstall-hook
+```
+
+!!! important
+
+    Gitlint cannot work together with an existing hook. If you already have a `.git/hooks/commit-msg`
+    file in your local repository, gitlint will refuse to install the `commit-msg` hook. Gitlint will also only
+    uninstall unmodified commit-msg hooks that were installed by gitlint.
+    If you're looking to use gitlint in conjunction with other hooks, you should consider
+    [using gitlint with pre-commit](#pre-commit).
+
+## Pre-commit
+
+`gitlint` can be configured as a plugin for the [pre-commit](https://pre-commit.com) git hooks
+framework.  Simply add the following configuration to your `.pre-commit-config.yaml`:
+
+```yaml
+-   repo: https://github.com/jorisroovers/gitlint
+    rev:  # Fill in a tag / sha here (e.g. v0.19.1)
+    hooks:
+    -   id: gitlint
+```
+
+You then need to install the pre-commit hook like so:
+```sh
+pre-commit install --hook-type commit-msg
+```
+!!! important
+
+    It's important that you run `pre-commit install --hook-type commit-msg`, even if you've already used
+    `pre-commit install` before. `pre-commit install` does **not** install commit-msg hooks by default!
+
+To manually trigger gitlint using `pre-commit` for your last commit message, use the following command:
+```sh
+pre-commit run gitlint --hook-stage commit-msg --commit-msg-filename .git/COMMIT_EDITMSG
+```
+
+In case you want to change gitlint's behavior, you should either [use a `.gitlint` file](configuration/gitlint_file.md)
+or modify the gitlint invocation in your `.pre-commit-config.yaml` file like so:
+```yaml
+-   repo: https://github.com/jorisroovers/gitlint
+    rev:  # Fill in a tag / sha here (e.g. v0.19.1)
+    hooks:
+    -   id: gitlint
+        args: [--contrib=CT1, --msg-filename]
+```
+
+!!! important
+
+    You need to add `--msg-filename` at the end of your custom `args` list as the gitlint-hook will fail otherwise.
+
+
+### gitlint and pre-commit in CI
+gitlint also supports a `gitlint-ci` pre-commit hook that can be used in CI environments.
+
+Configure it like so:
+```yaml
+-   repo: https://github.com/jorisroovers/gitlint
+    rev:  # Fill in a tag / sha here (e.g. v0.19.1)
+    hooks:
+    -   id: gitlint    # this is the regular commit-msg hook
+    -   id: gitlint-ci # hook for CI environments
+```
+
+And invoke it in your CI environment like this:
+
+```sh
+pre-commit run --hook-stage manual gitlint-ci
+```
+
+By default this will only lint the latest commit.
+If you want to lint more commits you can modify the `gitlint-ci` hook like so:
+
+```yaml
+-   repo: https://github.com/jorisroovers/gitlint
+    rev:  # Fill in a tag / sha here (e.g. v0.19.1)
+    hooks:
+    -   id: gitlint
+    -   id: gitlint-ci
+        args: [--debug, --commits, mybranch] # enable debug mode, lint all commits in mybranch
+```
\ No newline at end of file
diff --git a/docs/configuration.md b/docs/configuration.md
deleted file mode 100644
index af49d7c..0000000
--- a/docs/configuration.md
+++ /dev/null
@@ -1,628 +0,0 @@
-# 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
-```
-