From e2d38cd54491535f409372393baeed787c77388d Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Wed, 13 Oct 2021 07:34:57 +0200
Subject: Merging upstream version 0.16.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 docs/configuration.md          |  41 +++++++++++++++++++++++++++++++-
 docs/contributing.md           |   4 +++-
 docs/images/readme-gitlint.png | Bin 0 -> 348007 bytes
 docs/index.md                  |  52 +++++++++++++++++++++++------------------
 docs/rules.md                  |  31 ++++++++++++++++++++++++
 5 files changed, 103 insertions(+), 25 deletions(-)
 create mode 100644 docs/images/readme-gitlint.png

(limited to 'docs')

diff --git a/docs/configuration.md b/docs/configuration.md
index 50c4e63..226ba8a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -52,6 +52,12 @@ ignore-stdin=true
 # 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
+
 # Enable debug mode (prints more output). Disabled by default.
 debug=true
 
@@ -128,7 +134,7 @@ 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(.*)
+regex=(.*)release(.*)
 #
 # Ignore certain rules, you can reference them by their id or by their full name
 # Use 'all' to ignore all rules
@@ -139,6 +145,15 @@ ignore=T1,body-min-length
 # 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.
@@ -363,6 +378,30 @@ GITLINT_STAGED=1 gitlint       # using env variable
 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
+```
+
 ### ignore-stdin
 
 Ignore any stdin data. Sometimes useful when running gitlint in a CI server.
diff --git a/docs/contributing.md b/docs/contributing.md
index e58378c..d39f9e1 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -44,7 +44,9 @@ vagrant ssh
 Or you can choose to use your local environment:
 
 ```sh
-virtualenv .venv
+python -m venv .venv
+. .venv/bin/activate
+pip install --upgrade pip
 pip install -r requirements.txt -r test-requirements.txt -r doc-requirements.txt
 python setup.py develop
 ```
diff --git a/docs/images/readme-gitlint.png b/docs/images/readme-gitlint.png
new file mode 100644
index 0000000..516c915
Binary files /dev/null and b/docs/images/readme-gitlint.png differ
diff --git a/docs/index.md b/docs/index.md
index 5b371bf..98b72de 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -38,12 +38,11 @@ useful throughout the years.
 # Pip is recommended to install the latest version
 pip install gitlint
 
-# macOS
-brew install gitlint
-sudo port install gitlint  # alternative using macports
-
-# Ubuntu
-apt-get install gitlint
+# Community maintained packages:
+brew install gitlint       # Homebrew (macOS)
+sudo port install gitlint  # Macports (macOS)
+apt-get install gitlint    # Ubuntu
+# Other package managers, see https://repology.org/project/gitlint/versions
 
 # Docker: https://hub.docker.com/r/jorisroovers/gitlint
 docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint
@@ -134,8 +133,9 @@ Options:
                            current working directory]
   -C, --config FILE        Config file location [default: .gitlint]
   -c TEXT                  Config flags in format <rule>.<option>=<value>
-                           (e.g.: -c T1.line-length=80). Flag can be used
-                           multiple times to set multiple config values.
+                           (e.g.: -c T1.line-length=80). Flag can be
+                           used multiple times to set multiple config values.
+  --commit TEXT            Hash (SHA) of specific commit to lint.
   --commits TEXT           The range of commits to lint. [default: HEAD]
   -e, --extra-path PATH    Path to a directory or python module with extra
                            user-defined rules
@@ -147,10 +147,11 @@ Options:
                            server.
   --staged                 Read staged commit meta-info from the local
                            repository.
-  -v, --verbose            Verbosity, more v's for more verbose output (e.g.:
-                           -v, -vv, -vvv). [default: -vvv]
-  -s, --silent             Silent mode (no output). Takes precedence over -v,
-                           -vv, -vvv.
+  --fail-without-commits   Hard fail when the target commit range is empty.
+  -v, --verbose            Verbosity, more v's for more verbose output
+                           (e.g.: -v, -vv, -vvv). [default: -vvv]
+  -s, --silent             Silent mode (no output).
+                           Takes precedence over -v, -vv, -vvv.
   -d, --debug              Enable debugging output.
   --version                Show the version and exit.
   --help                   Show this message and exit.
@@ -159,6 +160,7 @@ Commands:
   generate-config  Generates a sample gitlint config file.
   install-hook     Install gitlint as a git commit-msg hook.
   lint             Lints a git repository [default command]
+  run-hook         Runs the gitlint commit-msg hook.
   uninstall-hook   Uninstall gitlint commit-msg hook.
 
   When no COMMAND is specified, gitlint defaults to 'gitlint lint'.
@@ -246,19 +248,21 @@ git log -1 --pretty=%B 62c0519 | gitlint
 Note that 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.
 
-## Linting a range of commits
+## Linting specific commits
 
-_Introduced in gitlint v0.9.0 (experimental in v0.8.0)_
+Gitlint allows users to lint a specific commit:
+```sh
+gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16
+gitlint --commit 019cf40 # short SHAs work too
+```
 
-Gitlint allows users to lint a number of commits at once like so:
+You can also lint multiple commits at once like so:
 
 ```sh
 # Lint a specific commit range:
 gitlint --commits "019cf40...d6bc75a"
 # You can also use git's special references:
 gitlint --commits "origin..HEAD"
-# Or specify a single specific commit in refspec format, like so:
-gitlint --commits "019cf40^...019cf40"
 ```
 
 The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood
@@ -271,9 +275,8 @@ script to lint an arbitrary set of commits, like shown in the example below.
 #!/bin/sh
 
 for commit in $(git rev-list master); do
-    commit_msg=$(git log -1 --pretty=%B $commit)
-    echo "$commit"
-    echo "$commit_msg" | gitlint
+    echo "Commit $commit"
+    gitlint --commit $commit
     echo "--------"
 done
 ```
@@ -309,7 +312,6 @@ general `ignore-merge-commits`, `ignore-revert-commits`,  `ignore-fixup-commits`
 [using one of the various ways to configure gitlint](configuration.md).
 
 ## Ignoring commits
-_Introduced in gitlint v0.10.0_
 
 You can configure gitlint to ignore specific commits or parts of a commit.
 
@@ -317,8 +319,7 @@ One way to do this, is to by [adding a gitline-ignore line to your commit messag
 
 If you have a case where you want to ignore a certain type of commits all-together, you can
 use gitlint's *ignore* rules.
-Here's an example gitlint file that configures gitlint to ignore rules `title-max-length` and `body-min-length`
-for all commits with a title starting with *"Release"*.
+Here's a few examples snippets from a `.gitlint` file:
 
 ```ini
 [ignore-by-title]
@@ -332,6 +333,11 @@ ignore=title-max-length,body-min-length
 # Match commits message bodies that have a line that contains 'release'
 regex=(.*)release(.*)
 ignore=all
+
+[ignore-by-author-name]
+# Match commits by author name (e.g. ignore all rules when a commit is made by dependabot)
+regex=dependabot
+ignore=all
 ```
 
 If you just want to ignore certain lines in a commit, you can do that using the
diff --git a/docs/rules.md b/docs/rules.md
index 9779c54..eb4b65e 100644
--- a/docs/rules.md
+++ b/docs/rules.md
@@ -30,6 +30,8 @@ M1    | author-valid-email          | >= 0.9.0          | Author email address m
 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
@@ -405,3 +407,32 @@ regex=(^Co-Authored-By)|(^Signed-off-by)
 [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
+```
\ No newline at end of file
-- 
cgit v1.2.3