Adding upstream version 0.18.0.upstream/0.18.0

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

1 files changed, 91 insertions, 27 deletions

diff --git a/docs/index.md b/docs/index.md
index 398b4e5..801a16e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -22,11 +22,11 @@ Great for use as a [commit-msg git hook](#using-gitlint-as-a-commit-msg-hook) or
  - **Easily integrated**: Gitlint is designed to work [with your own scripts or CI system](#using-gitlint-in-a-ci-environment).
  - **Sane defaults:** Many of gitlint's validations are based on
 [well-known](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
-[community](http://addamhardy.com/2013/06/05/good-commit-messages-and-enforcing-them-with-git-hooks.html),
+[community](https://addamhardy.com/2013-06-05-good-commit-messages-and-enforcing-them-with-git-hooks),
 [standards](http://chris.beams.io/posts/git-commit/), others are based on checks that we've found
 useful throughout the years.
  - **Easily configurable:** Gitlint has sane defaults, but [you can also easily customize it to your own liking](configuration.md).
- - **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules).
+ - **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules.md).
  - **User-defined rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules.md).
  - **Full unicode support:** Lint your Russian, Chinese or Emoji commit messages with ease!
  - **Production-ready:** Gitlint checks a lot of the boxes you're looking for: actively maintained, high unit test coverage, integration tests,
@@ -38,6 +38,10 @@ useful throughout the years.
 # Pip is recommended to install the latest version
 pip install gitlint
 
+# Alternative: by default, gitlint is installed with pinned dependencies.
+# To install gitlint with looser dependency requirements, only install gitlint-core.
+pip install gitlint-core
+
 # Community maintained packages:
 brew install gitlint       # Homebrew (macOS)
 sudo port install gitlint  # Macports (macOS)
@@ -81,6 +85,19 @@ $ cat examples/commit-message-2 | gitlint
 !!! note
     The returned exit code equals the number of errors found. [Some exit codes are special](index.md#exit-codes).
 
+### Shell completion
+
+```sh
+# Bash: add to ~/.bashrc
+eval "$(_GITLINT_COMPLETE=bash_source gitlint)"
+
+# Zsh: add to ~/.zshrc
+eval "$(_GITLINT_COMPLETE=zsh_source gitlint)"
+
+# Fish: add to ~/.config/fish/completions/foo-bar.fish
+eval (env _GITLINT_COMPLETE=fish_source gitlint)
+```
+
 ## Configuration
 
 For in-depth documentation of general and rule-specific configuration options, have a look at the [Configuration](configuration.md) and [Rules](rules.md) pages.
@@ -93,7 +110,7 @@ Short example `.gitlint` file ([full reference](configuration.md)):
 # their id or by their full name
 ignore=body-is-missing,T3
 
-# Ignore any data send to gitlint via stdin
+# Ignore any data sent to gitlint via stdin
 ignore-stdin=true
 
 # Configure title-max-length rule, set title length to 80 (72 = default)
@@ -136,7 +153,8 @@ Options:
                            (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]
+  --commits TEXT           The range of commits (refspec or comma-separated
+                           hashes) to lint. [default: HEAD]
   -e, --extra-path PATH    Path to a directory or python module with extra
                            user-defined rules
   --ignore TEXT            Ignore rules (comma-separated by id or name).
@@ -145,8 +163,9 @@ Options:
   --msg-filename FILENAME  Path to a file containing a commit-msg.
   --ignore-stdin           Ignore any stdin data. Useful for running in CI
                            server.
-  --staged                 Read staged commit meta-info from the local
-                           repository.
+  --staged                 Attempt smart guesses about meta info (like
+                           author name, email, branch, changed files, etc)
+                           for staged commits.
   --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]
@@ -218,7 +237,7 @@ In case you want to change gitlint's behavior, you should either use a `.gitlint
 your `.pre-commit-config.yaml` file like so:
 ```yaml
 -   repo: https://github.com/jorisroovers/gitlint
-    rev:  # Fill in a tag / sha here
+    rev:  # Fill in a tag / sha here (e.g. v0.18.0)
     hooks:
     -   id: gitlint
         args: [--contrib=CT1, --msg-filename]
@@ -229,6 +248,36 @@ your `.pre-commit-config.yaml` file like so:
     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:  # insert ref, e.g. v0.18.0
+    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:  v0.17.0
+    hooks:
+    -   id: gitlint
+    -   id: gitlint-ci
+        args: [--debug, --commits, mybranch] # enable debug mode, lint all commits in mybranch
+```
+
 ## 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.
@@ -248,33 +297,48 @@ 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 specific commits
+## Linting specific commits or branches
 
-Gitlint allows users to lint a specific commit:
+Gitlint can lint specific commits using `--commit`:
 ```sh
 gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16
-gitlint --commit 019cf40 # short SHAs work too
+gitlint --commit 019cf40  # short SHAs work too
+gitlint --commit HEAD~2   # as do special references
+gitlint --commit mybranch # lint latest commit on a branch 
 ```
 
-You can also lint multiple commits at once like so:
+You can also lint multiple commits using `--commits` (plural):
 
 ```sh
 # Lint a specific commit range:
 gitlint --commits "019cf40...d6bc75a"
-# You can also use git's special references:
+# Lint all commits on a branch
+gitlint --commits mybranch
+# Lint all commits that are different between a branch and your main branch
+gitlint --commits "main..mybranch"
+# Use git's special references
 gitlint --commits "origin..HEAD"
+
+# You can also pass multiple, comma separated commit hashes:
+gitlint --commits 019cf40,c50eb150,d6bc75a
+# These can include special references as well
+gitlint --commits HEAD~1,mybranch-name,origin/main,d6bc75a
 ```
 
 The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood
 by [git rev-list](https://git-scm.com/docs/git-rev-list) as a single argument will work.
 
+Alternatively, you can pass `--commits` a comma-separated list of commit hashes (both short and full-length SHAs work,
+as well as special references such as `HEAD` and branch names).
+Gitlint will treat these as pointers to **single** commits and lint these in the order you passed.
+
 For cases where the `--commits` option doesn't provide the flexibility you need, you can always use a simple shell
 script to lint an arbitrary set of commits, like shown in the example below.
 
 ```sh
 #!/bin/sh
 
-for commit in $(git rev-list master); do
+for commit in $(git rev-list my-branch); do
     echo "Commit $commit"
     gitlint --commit $commit
     echo "--------"
@@ -283,14 +347,14 @@ done
 
 !!! note
     One downside to this approach is that you invoke gitlint once per commit vs. once per set of commits.
-    This means you'll incur the gitlint startup time once per commit, making this approach rather slow if you want to
+    This means you'll incur the gitlint startup time once per commit, making it rather slow if you want to
     lint a large set of commits. Always use `--commits` if you can to avoid this performance penalty.
 
 
 ## Merge, fixup, squash and revert commits
-_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash) and v0.13.0 (revert)_
+_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash), v0.13.0 (revert) and v0.18.0 (fixup=amend)_
 
-**Gitlint ignores merge, revert, fixup and squash commits by default.**
+**Gitlint ignores merge, revert, fixup, and squash commits by default.**
 
 For merge and revert commits, the rationale for ignoring them is
 that most users keep git's default messages for these commits (i.e *Merge/Revert "[original commit message]"*).
@@ -300,14 +364,14 @@ For example, a common case is that *"Merge:"* being auto-prepended triggers a
 [title-max-length](rules.md#t1-title-max-length) violation. Most users don't want this, so we disable linting
 on Merge and Revert commits by default.
 
-For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits, the rationale is that these are temporary
+For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) (including [fixup=amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)) commits, the rationale is that these are temporary
 commits that will be squashed into a different commit, and hence the commit messages for these commits are very
-short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"* or
-*"squash!"* to your commit message, certain gitlint rules might be violated
+short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"*,
+*"amend!"* or *"squash!"* to your commit message, certain gitlint rules might be violated
 (e.g. [title-max-length](rules.md#t1-title-max-length)) which is often undesirable.
 
 In case you *do* want to lint these commit messages, you can disable this behavior by setting the
-general `ignore-merge-commits`, `ignore-revert-commits`,  `ignore-fixup-commits` or
+general `ignore-merge-commits`, `ignore-revert-commits`,  `ignore-fixup-commits`, `ignore-fixup-amend-commits` or
 `ignore-squash-commits` option to `false`
 [using one of the various ways to configure gitlint](configuration.md).
 
@@ -374,7 +438,7 @@ additional unique identifier (i.e. the rule *name*) during configuration.
     For example, by defining 2 `body-max-line-length` rules with different `line-length` options, you obviously create
     a conflicting situation. Gitlint does not do any resolution of such conflicts, it's up to you to make sure
     any configuration is non-conflicting. So caution advised!
-    
+
 Defining a named rule is easy, for example using your `.gitlint` file:
 
 ```ini
@@ -400,7 +464,7 @@ When executing gitlint, you will see the violations from the default `title-must
 the violations caused by the additional Named Rules.
 
 ```sh
-$ gitlint 
+$ gitlint
 1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: foo wonderwoman hur bar"
 1: T5:This-Can_Be*Whatever$YouWant Title contains the word 'wonderwoman' (case-insensitive): "WIP: foo wonderwoman hur bar"
 1: T5:extra-words Title contains the word 'foo' (case-insensitive): "WIP: foo wonderwoman hur bar"
@@ -431,8 +495,8 @@ of violations counted by the exit code is 252. Note that gitlint does not have a
 it can detect, it will just always return with exit code 252 when the number of violations is greater than or equal
 to 252.
 
-Exit Code  | Description
------------|------------------------------------------------------------
-253        | Wrong invocation of the `gitlint` command.
-254        | Something went wrong when invoking git.
-255        | Invalid gitlint configuration
+| Exit Code | Description                                |
+| --------- | ------------------------------------------ |
+| 253       | Wrong invocation of the `gitlint` command. |
+| 254       | Something went wrong when invoking git.    |
+| 255       | Invalid gitlint configuration              |