Documentation updates

- Upgraded to latest mkdocs - Updated rule documentation with more configuration examples - Replaced triple backticks with single backticks for inline fixed text - Replaced bash with sh for shell blocks - Removed trailing hashes in markdown titles - Workaround for mkdocs table formatting issue, see mkdocs/mkdocs#2028) - Documented docker slowness issue (closes #129)
jorisroovers · Sep 11, 2020 · 7d6d5bc · 7d6d5bc
1 parent cb94a49
commit 7d6d5bc
Show file tree

Hide file tree

Showing 11 changed files with 316 additions and 206 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/Dockerfile b/Dockerfile
@@ -1,10 +1,13 @@
 # User-facing Dockerfile. For development, see Dockerfile.dev and ./run_tests.sh -h
 
 # To lint your current working directory:
-# docker run -v $(pwd):/repo jorisroovers/gitlint
+# docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint
 
 # With arguments:
-# docker run -v $(pwd):/repo jorisroovers/gitlint --debug --ignore T1
+# docker --ulimit nofile=1024 run -v $(pwd):/repo jorisroovers/gitlint --debug --ignore T1
+
+# NOTE: --ulimit is required to work around a limitation in Docker
+# Details: https://github.com/jorisroovers/gitlint/issues/129
 
 FROM python:3.8-alpine
 ARG GITLINT_VERSION

diff --git a/doc-requirements.txt b/doc-requirements.txt
@@ -1 +1 @@
-mkdocs==1.0.4
+mkdocs==1.1.2
diff --git 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
@@ -99,6 +99,11 @@ 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
@@ -123,6 +128,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 +141,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 +164,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,35 +176,35 @@ 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```)
+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
 
-# 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```
+ false         | >= 0.1.0         | `--silent`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --silent
 ```
 
-## verbosity
+### verbosity
 
 Amount of output gitlint will show when printing errors.
 
@@ -203,7 +213,7 @@ Default value  |  gitlint version | commandline flag
  3             | >= 0.1.0         | `-v`
 
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -vvv                   # default     (level 3)
@@ -219,15 +229,15 @@ gitlint -c general.verbosity=0 # Same as --silent
 verbosity=2
 ```
 
-## ignore-merge-commits
+### ignore-merge-commits
 
 Whether or not to ignore merge commits.
 
 Default value  |  gitlint version | commandline flag  
 ---------------|------------------|-------------------
  true          | >= 0.7.0         | Not Available
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -c general.ignore-merge-commits=false
@@ -238,15 +248,15 @@ gitlint -c general.ignore-merge-commits=false
 ignore-merge-commits=false
 ```
 
-## ignore-revert-commits
+### ignore-revert-commits
 
 Whether or not to ignore revert commits.
 
 Default value  |  gitlint version | commandline flag  
 ---------------|------------------|-------------------
  true          | >= 0.13.0        | Not Available
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -c general.ignore-revert-commits=false
@@ -257,15 +267,15 @@ gitlint -c general.ignore-revert-commits=false
 ignore-revert-commits=false
 ```
 
-## ignore-fixup-commits
+### 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  
 ---------------|------------------|-------------------
  true          | >= 0.9.0         | Not Available
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -c general.ignore-fixup-commits=false
@@ -276,15 +286,15 @@ gitlint -c general.ignore-fixup-commits=false
 ignore-fixup-commits=false
 ```
 
-## ignore-squash-commits
+### 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  
 ---------------|------------------|-------------------
  true          | >= 0.9.0         | Not Available
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint -c general.ignore-squash-commits=false
@@ -295,15 +305,15 @@ gitlint -c general.ignore-squash-commits=false
 ignore-squash-commits=false
 ```
 
-## ignore
+### ignore
 
 Comma separated list of rules to ignore (by name or id).
 
 Default value              |  gitlint version | commandline flag  
 ---------------------------|------------------|-------------------
  [] (=empty list)          | >= 0.1.0         | `--ignore`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --ignore=body-min-length              # ignore single rule
@@ -316,31 +326,31 @@ gitlint -c general.ignore=T1,body-min-length  # different way of doing the same
 ignore=T1,body-min-length
 ```
 
-## debug
+### debug
 
 Enable debugging output.
 
 Default value  |  gitlint version | commandline flag  
 ---------------|------------------|-------------------
  false         | >= 0.7.1         | `--debug`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --debug
 # --debug is special, the following does NOT work
 # gitlint -c general.debug=true
 ```
 
-## target
+### target
 
 Target git repository gitlint should be linting against.
 
 Default value              |  gitlint version | commandline flag  
 ---------------------------|------------------|-------------------
  (empty)                   | >= 0.8.0         | `--target`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --target=/home/joe/myrepo/
@@ -352,15 +362,15 @@ gitlint -c general.target=/home/joe/myrepo/  # different way of doing the same
 target=/home/joe/myrepo/
 ```
 
-## extra-path
+### extra-path
 
 Path where gitlint looks for [user-defined rules](user_defined_rules.md).
 
 Default value              |  gitlint version | commandline flag  
 ---------------------------|------------------|-------------------
  (empty)                   | >= 0.8.0         | `--extra-path`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --extra-path=/home/joe/rules/
@@ -372,15 +382,15 @@ gitlint -c general.extra-path=/home/joe/rules/  # different way of doing the sam
 extra-path=/home/joe/rules/
 ```
 
-## contrib
+### contrib
 
 [Contrib rules](contrib_rules) to enable.
 
 Default value              |  gitlint version | commandline flag  
 ---------------------------|------------------|-------------------
  (empty)                   | >= 0.12.0        | `--contrib`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --contrib=contrib-title-conventional-commits,CC1
@@ -391,15 +401,15 @@ gitlint -c general.contrib=contrib-title-conventional-commits,CC1  # different w
 [general]
 contrib=contrib-title-conventional-commits,CC1
 ```
-## ignore-stdin
+### ignore-stdin
 
 Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
 
 Default value  |  gitlint version | commandline flag  
 ---------------|------------------|-------------------
  false         | >= 0.12.0        | `--ignore-stdin`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --ignore-stdin
@@ -411,15 +421,15 @@ gitlint -c general.ignore-stdin=true # different way of doing the same
 ignore-stdin=true
 ```
 
-## staged
+### staged
 
-Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or ```--commit-msg```.
+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.13.0        | `--staged`
 
-### Examples
+#### Examples
 ```sh
 # CLI
 gitlint --staged

diff --git a/docs/contrib_rules.md b/docs/contrib_rules.md
@@ -7,7 +7,7 @@ Contrib rules are meant to augment default gitlint behavior by providing users w
 forcing these rules on all gitlint users. This also means that users don't have to
 re-implement these commonly used rules themselves as [user-defined](user_defined_rules) rules.
 
-To enable certain contrib rules, you can use the ```--contrib``` flag.
+To enable certain contrib rules, you can use the `--contrib` flag.
 ```sh
 $ cat examples/commit-message-1 | gitlint --contrib contrib-title-conventional-commits,CC1
 1: CC1 Body does not contain a 'Signed-Off-By' line
@@ -20,7 +20,7 @@ $ cat examples/commit-message-1 | gitlint --contrib contrib-title-conventional-c
 3: B1 Line exceeds max length (123>80): "Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120."
 ```
 
-Same thing using a ```.gitlint``` file:
+Same thing using a `.gitlint` file:
 
 ```ini
 [general]
@@ -36,7 +36,7 @@ types = bugfix,user-story,epic
 
 You can also configure contrib rules using [any of the other ways to configure gitlint](configuration.md).
 
-# Available Contrib Rules
+## Available Contrib Rules
 
 ID    | Name                                | gitlint version   | Description
 ------|-------------------------------------|------------------ |-------------------------------------------
@@ -63,5 +63,5 @@ ID    | Name                                  | gitlint version    | Description
 CC1   | contrib-requires-signed-off-by        | >= 0.12.0          | Commit body must contain a `Signed-Off-By` line. This means, a line that starts with the `Signed-Off-By` keyword.
 
 
-# Contributing Contrib rules
+## Contributing Contrib rules
 We'd love for you to contribute new Contrib rules to gitlint or improve existing ones! Please visit the [Contributing](contributing) page on how to get started.