Deployed 0e09989 with MkDocs version: 1.1.2

8 files changed, 30 insertions, 30 deletions

diff --git a/contrib_rules/index.html b/contrib_rules/index.html
index 078be35..85412d4 100644
--- a/contrib_rules/index.html
+++ b/contrib_rules/index.html
@@ -67,7 +67,7 @@
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#ct1-contrib-title-conventional-commits">CT1: contrib-title-conventional-commits</a>
     </li>
-    <li class="toctree-l2"><a class="reference internal" href="#cc1-contrib-requires-signed-off-by">CC1: contrib-requires-signed-off-by</a>
+    <li class="toctree-l2"><a class="reference internal" href="#cc1-contrib-body-requires-signed-off-by">CC1: contrib-body-requires-signed-off-by</a>
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#contributing-contrib-rules">Contributing Contrib rules</a>
     </li>
@@ -129,7 +129,7 @@ forcing these rules on all gitlint users. This also means that users don't have
 re-implement these commonly used rules themselves as <a href="user_defined_rules">user-defined</a> rules.</p>
 <p>To enable certain contrib rules, you can use the <code>--contrib</code> flag.</p>
 <pre><code class="language-sh">$ cat examples/commit-message-1 | gitlint --contrib contrib-title-conventional-commits,CC1
-1: CC1 Body does not contain a 'Signed-Off-By' line
+1: CC1 Body does not contain a 'Signed-off-by' line
 1: CL1 Title does not start with one of fix, feat, chore, docs, style, refactor, perf, test: &quot;WIP: This is the title of a commit message.&quot;
 
 # These are the default violations
@@ -169,9 +169,9 @@ types = bugfix,user-story,epic
 </tr>
 <tr>
 <td>CC1</td>
-<td>contrib-requires-signed-off-by</td>
+<td>contrib-body-requires-signed-off-by</td>
 <td>&gt;= 0.12.0</td>
-<td>Commit body must contain a <code>Signed-Off-By</code> line.</td>
+<td>Commit body must contain a <code>Signed-off-by</code> line.</td>
 </tr>
 </tbody>
 </table>
@@ -213,7 +213,7 @@ types = bugfix,user-story,epic
 </tr>
 </tbody>
 </table>
-<h2 id="cc1-contrib-requires-signed-off-by">CC1: contrib-requires-signed-off-by</h2>
+<h2 id="cc1-contrib-body-requires-signed-off-by">CC1: contrib-body-requires-signed-off-by</h2>
 <table>
 <thead>
 <tr>
@@ -226,9 +226,9 @@ types = bugfix,user-story,epic
 <tbody>
 <tr>
 <td>CC1</td>
-<td>contrib-requires-signed-off-by</td>
+<td>contrib-body-requires-signed-off-by</td>
 <td>&gt;= 0.12.0</td>
-<td>Commit body must contain a <code>Signed-Off-By</code> line. This means, a line that starts with the <code>Signed-Off-By</code> keyword.</td>
+<td>Commit body must contain a <code>Signed-off-by</code> line. This means, a line that starts with the <code>Signed-off-by</code> keyword.</td>
 </tr>
 </tbody>
 </table>
diff --git a/demos/asciicinema.json b/demos/asciicinema.json
index b499765..c6e2747 100644
--- a/demos/asciicinema.json
+++ b/demos/asciicinema.json
@@ -2412,7 +2412,7 @@
     ],
     [
       0.000020,
-      "gitlint: \u001b[31mYour commit message contains the above violations.\u001b[0m\r\n"
+      "gitlint: \u001b[31mYour commit message contains violations.\u001b[0m\r\n"
     ],
     [
       0.002541,
diff --git a/index.html b/index.html
index 8cdbb17..0089c22 100644
--- a/index.html
+++ b/index.html
@@ -570,5 +570,5 @@ to 252.</p>
 
 <!--
 MkDocs version : 1.1.2
-Build Date UTC : 2020-11-27 11:15:29.715435+00:00
+Build Date UTC : 2021-04-16 21:25:17.304869+00:00
 -->
diff --git a/rules/index.html b/rules/index.html
index 1e34a54..850afb2 100644
--- a/rules/index.html
+++ b/rules/index.html
@@ -212,7 +212,7 @@ what you're looking for.</p>
 </tr>
 <tr>
 <td>T8</td>
-<td>title-max-length</td>
+<td>title-min-length</td>
 <td>&gt;= 0.14.0</td>
 <td>Title length must be &gt; 5 chars.</td>
 </tr>
@@ -1034,9 +1034,9 @@ ignore=T1,body-min-length,B6
 [ignore-body-lines]
 regex=^Co-Authored-By
 
-# Ignore lines that start with 'Co-Authored-By' or with 'Signed-Off-By'
+# Ignore lines that start with 'Co-Authored-By' or with 'Signed-off-by'
 [ignore-body-lines]
-regex=(^Co-Authored-By)|(^Signed-Off-By)
+regex=(^Co-Authored-By)|(^Signed-off-by)
 
 # Ignore lines that contain 'foobar'
 [ignore-body-lines]
diff --git a/search/search_index.json b/search/search_index.json
index 072b687..cefc0f1 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction Gitlint is a git commit message linter written in python: it checks your commit messages for style. Great for use as a commit-msg git hook or as part of your gating script in a CI pipeline (e.g. Jenkins) . Note Gitlint support for Windows is experimental , and there are some known issues . Also, gitlint is not the only git commit message linter out there, if you are looking for an alternative written in a different language, have a look at fit-commit (Ruby), node-commit-msg (Node.js) or commitlint (Node.js). Important Gitlint no longer supports Python 2.7 and Python 3.5 as they have reached End-Of-Life . The last gitlint version to support Python 2.7 and Python 3.5 is 0.14.0 (released on October 24th, 2020). Features Commit message hook : Auto-trigger validations against new commit message right when you're committing . Also works with pre-commit . Easily integrated : Gitlint is designed to work with your own scripts or CI system . Sane defaults: Many of gitlint's validations are based on well-known , community , standards , 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 . Community contributed rules : Conventions that are common but not universal can be selectively enabled . User-defined rules: Want to do more then what gitlint offers out of the box? Write your own user defined rules . 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, python code standards (pep8, pylint), good documentation, widely used, proven track record. Getting Started Installation # 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 # Docker: https://hub.docker.com/r/jorisroovers/gitlint docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint # NOTE: --ulimit is required to work around a limitation in Docker # Details: https://github.com/jorisroovers/gitlint/issues/129 Usage # Check the last commit message gitlint # Alternatively, pipe a commit message to gitlint: cat examples/commit-message-1 | gitlint # or git log -1 --pretty=%B | gitlint # Or read the commit-msg from a file, like so: gitlint --msg-filename examples/commit-message-2 # Lint all commits in your repo gitlint --commits HEAD # To install a gitlint as a commit-msg git hook: gitlint install-hook Output example: $ cat examples/commit-message-2 | gitlint 1: T1 Title exceeds max length (134>80): \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 1: T2 Title has trailing whitespace: \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 1: T4 Title contains hard tab characters (\\t): \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 2: B4 Second line is not empty: \"This line should not contain text\" 3: B1 Line exceeds max length (125>80): \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" 3: B2 Line has trailing whitespace: \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" 3: B3 Line contains hard tab characters (\\t): \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" Note The returned exit code equals the number of errors found. Some exit codes are special . Configuration For in-depth documentation of general and rule-specific configuration options, have a look at the Configuration and Rules pages. Short example .gitlint file ( full reference ): [general] # Ignore certain rules (comma-separated list), you can reference them by # their id or by their full name ignore=body-is-missing,T3 # Ignore any data send to gitlint via stdin ignore-stdin=true # Configure title-max-length rule, set title length to 80 (72 = default) [title-max-length] line-length=80 # You can also reference rules by their id (B1 = body-max-line-length) [B1] line-length=123 Example use of flags: # Change gitlint's verbosity. $ gitlint -v # Ignore certain rules $ gitlint --ignore body-is-missing,T3 # Enable debug mode $ gitlint --debug # Load user-defined rules (see http://jorisroovers.github.io/gitlint/user_defined_rules) $ gitlint --extra-path /home/joe/mygitlint_rules Other commands and variations: $ gitlint --help Usage: gitlint [OPTIONS] COMMAND [ARGS]... Git lint tool, checks your git commit messages for styling issues Documentation: http://jorisroovers.github.io/gitlint Options: --target DIRECTORY Path of the target git repository. [default: 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. --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 --ignore TEXT Ignore rules (comma-separated by id or name). --contrib TEXT Contrib rules to enable (comma-separated by id or name). --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. -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. 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] uninstall-hook Uninstall gitlint commit-msg hook. When no COMMAND is specified, gitlint defaults to 'gitlint lint'. Using gitlint as a commit-msg hook Introduced in gitlint v0.4.0 You can also install gitlint as a git commit-msg hook so that gitlint checks your commit messages automatically after each commit. gitlint install-hook # To 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 . Using gitlint through pre-commit gitlint can be configured as a plugin for the pre-commit git hooks framework. Simply add the configuration to your .pre-commit-config.yaml : - repo: https://github.com/jorisroovers/gitlint rev: # Fill in a tag / sha here hooks: - id: gitlint You then need to install the pre-commit hook like so: 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: 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 (see Configuration ) or modify the gitlint invocation in your .pre-commit-config.yaml file like so: - repo: https://github.com/jorisroovers/gitlint rev: # Fill in a tag / sha here 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. 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 . 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: # lint the last commit message git log -1 --pretty=%B | gitlint # lint a specific commit: 62c0519 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 Introduced in gitlint v0.9.0 (experimental in v0.8.0) Gitlint allows users to lint a number of commits at once like so: # 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 by git rev-list as a single argument will work. 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. #!/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 \"--------\" 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 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) 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]\" ). Often times these commit messages are also auto-generated through tools like github. These default/auto-generated commit messages tend to cause gitlint violations. For example, a common case is that \"Merge:\" being auto-prepended triggers a title-max-length violation. Most users don't want this, so we disable linting on Merge and Revert commits by default. For squash and fixup 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 (e.g. 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 ignore-squash-commits option to false using one of the various ways to configure gitlint . Ignoring commits Introduced in gitlint v0.10.0 You can configure gitlint to ignore specific commits or parts of a commit. One way to do this, is to by adding a gitline-ignore line to your commit message . 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\" . [ignore-by-title] # Match commit titles starting with Release regex=^Release(.*) ignore=title-max-length,body-min-length # ignore all rules by setting ignore to 'all' # ignore=all [ignore-by-body] # Match commits message bodies that have a line that contains 'release' regex=(.*)release(.*) ignore=all If you just want to ignore certain lines in a commit, you can do that using the ignore-body-lines rule. # Ignore all lines that start with 'Co-Authored-By' [ignore-body-lines] regex=^Co-Authored-By Warning When ignoring specific lines, gitlint will no longer be aware of them while applying other rules. This can sometimes be confusing for end-users, especially as line numbers of violations will typically no longer match line numbers in the original commit message. Make sure to educate your users accordingly. Note If you want to implement more complex ignore rules according to your own logic, you can do so using user-defined configuration rules . Named Rules Introduced in gitlint v0.14.0 Named rules allow you to have multiple of the same rules active at the same time, which allows you to enforce the same rule multiple times but with different options. Named rules are so-called because they require an additional unique identifier (i.e. the rule name ) during configuration. Warning Named rules is an advanced topic. It's easy to make mistakes by defining conflicting instances of the same rule. 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: # By adding the following section, you will add a second instance of the # title-must-not-contain-word (T5) rule (in addition to the one that is enabled # by default) with the name 'extra-words'. [title-must-not-contain-word:extra-words] words=foo,bar # So the generic form is # [<rule-id-or-name>:<your-chosen-name>] # Another example, referencing the rule type by id [T5:more-words] words=hur,dur # You can add as many additional rules and you can name them whatever you want # The only requirement is that names cannot contain whitespace or colons (:) [title-must-not-contain-word:This-Can_Be*Whatever$YouWant] words=wonderwoman,batman,power ranger When executing gitlint, you will see the violations from the default title-must-not-contain-word (T5) rule, as well as the violations caused by the additional Named Rules. $ 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\" 1: T5:extra-words Title contains the word 'bar' (case-insensitive): \"WIP: foo wonderwoman hur bar\" 1: T5:more-words Title contains the word 'hur' (case-insensitive): \"WIP: foo wonderwoman hur bar\" Named rules are further treated identical to all other rules in gitlint: You can reference them by their full name, when e.g. adding them to your ignore configuration # .gitlint file example [general] ignore=T5:more-words,title-must-not-contain-word:extra-words You can use them to instantiate multiple of the same user-defined rule You can configure them using any of the ways you can configure regular gitlint rules Exit codes Gitlint uses the exit code as a simple way to indicate the number of violations found. Some exit codes are used to indicate special errors as indicated in the table below. Because of these special error codes and the fact that bash only supports exit codes between 0 and 255 , the maximum number of violations counted by the exit code is 252. Note that gitlint does not have a limit on the number of violations 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","title":"Home"},{"location":"#introduction","text":"Gitlint is a git commit message linter written in python: it checks your commit messages for style. Great for use as a commit-msg git hook or as part of your gating script in a CI pipeline (e.g. Jenkins) . Note Gitlint support for Windows is experimental , and there are some known issues . Also, gitlint is not the only git commit message linter out there, if you are looking for an alternative written in a different language, have a look at fit-commit (Ruby), node-commit-msg (Node.js) or commitlint (Node.js). Important Gitlint no longer supports Python 2.7 and Python 3.5 as they have reached End-Of-Life . The last gitlint version to support Python 2.7 and Python 3.5 is 0.14.0 (released on October 24th, 2020).","title":"Introduction"},{"location":"#features","text":"Commit message hook : Auto-trigger validations against new commit message right when you're committing . Also works with pre-commit . Easily integrated : Gitlint is designed to work with your own scripts or CI system . Sane defaults: Many of gitlint's validations are based on well-known , community , standards , 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 . Community contributed rules : Conventions that are common but not universal can be selectively enabled . User-defined rules: Want to do more then what gitlint offers out of the box? Write your own user defined rules . 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, python code standards (pep8, pylint), good documentation, widely used, proven track record.","title":"Features"},{"location":"#getting-started","text":"","title":"Getting Started"},{"location":"#installation","text":"# 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 # Docker: https://hub.docker.com/r/jorisroovers/gitlint docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint # NOTE: --ulimit is required to work around a limitation in Docker # Details: https://github.com/jorisroovers/gitlint/issues/129","title":"Installation"},{"location":"#usage","text":"# Check the last commit message gitlint # Alternatively, pipe a commit message to gitlint: cat examples/commit-message-1 | gitlint # or git log -1 --pretty=%B | gitlint # Or read the commit-msg from a file, like so: gitlint --msg-filename examples/commit-message-2 # Lint all commits in your repo gitlint --commits HEAD # To install a gitlint as a commit-msg git hook: gitlint install-hook Output example: $ cat examples/commit-message-2 | gitlint 1: T1 Title exceeds max length (134>80): \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 1: T2 Title has trailing whitespace: \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 1: T4 Title contains hard tab characters (\\t): \"This is the title of a commit message that is over 80 characters and contains hard tabs and trailing whitespace and the word wiping \" 2: B4 Second line is not empty: \"This line should not contain text\" 3: B1 Line exceeds max length (125>80): \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" 3: B2 Line has trailing whitespace: \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" 3: B3 Line contains hard tab characters (\\t): \"Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120. \" Note The returned exit code equals the number of errors found. Some exit codes are special .","title":"Usage"},{"location":"#configuration","text":"For in-depth documentation of general and rule-specific configuration options, have a look at the Configuration and Rules pages. Short example .gitlint file ( full reference ): [general] # Ignore certain rules (comma-separated list), you can reference them by # their id or by their full name ignore=body-is-missing,T3 # Ignore any data send to gitlint via stdin ignore-stdin=true # Configure title-max-length rule, set title length to 80 (72 = default) [title-max-length] line-length=80 # You can also reference rules by their id (B1 = body-max-line-length) [B1] line-length=123 Example use of flags: # Change gitlint's verbosity. $ gitlint -v # Ignore certain rules $ gitlint --ignore body-is-missing,T3 # Enable debug mode $ gitlint --debug # Load user-defined rules (see http://jorisroovers.github.io/gitlint/user_defined_rules) $ gitlint --extra-path /home/joe/mygitlint_rules Other commands and variations: $ gitlint --help Usage: gitlint [OPTIONS] COMMAND [ARGS]... Git lint tool, checks your git commit messages for styling issues Documentation: http://jorisroovers.github.io/gitlint Options: --target DIRECTORY Path of the target git repository. [default: 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. --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 --ignore TEXT Ignore rules (comma-separated by id or name). --contrib TEXT Contrib rules to enable (comma-separated by id or name). --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. -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. 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] uninstall-hook Uninstall gitlint commit-msg hook. When no COMMAND is specified, gitlint defaults to 'gitlint lint'.","title":"Configuration"},{"location":"#using-gitlint-as-a-commit-msg-hook","text":"Introduced in gitlint v0.4.0 You can also install gitlint as a git commit-msg hook so that gitlint checks your commit messages automatically after each commit. gitlint install-hook # To 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 .","title":"Using gitlint as a commit-msg hook"},{"location":"#using-gitlint-through-pre-commit","text":"gitlint can be configured as a plugin for the pre-commit git hooks framework. Simply add the configuration to your .pre-commit-config.yaml : - repo: https://github.com/jorisroovers/gitlint rev: # Fill in a tag / sha here hooks: - id: gitlint You then need to install the pre-commit hook like so: 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: 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 (see Configuration ) or modify the gitlint invocation in your .pre-commit-config.yaml file like so: - repo: https://github.com/jorisroovers/gitlint rev: # Fill in a tag / sha here 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.","title":"Using gitlint through pre-commit"},{"location":"#using-gitlint-in-a-ci-environment","text":"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 . 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: # lint the last commit message git log -1 --pretty=%B | gitlint # lint a specific commit: 62c0519 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.","title":"Using gitlint in a CI environment"},{"location":"#linting-a-range-of-commits","text":"Introduced in gitlint v0.9.0 (experimental in v0.8.0) Gitlint allows users to lint a number of commits at once like so: # 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 by git rev-list as a single argument will work. 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. #!/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 \"--------\" 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 lint a large set of commits. Always use --commits if you can to avoid this performance penalty.","title":"Linting a range of commits"},{"location":"#merge-fixup-squash-and-revert-commits","text":"Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash) and v0.13.0 (revert) 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]\" ). Often times these commit messages are also auto-generated through tools like github. These default/auto-generated commit messages tend to cause gitlint violations. For example, a common case is that \"Merge:\" being auto-prepended triggers a title-max-length violation. Most users don't want this, so we disable linting on Merge and Revert commits by default. For squash and fixup 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 (e.g. 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 ignore-squash-commits option to false using one of the various ways to configure gitlint .","title":"Merge, fixup, squash and revert commits"},{"location":"#ignoring-commits","text":"Introduced in gitlint v0.10.0 You can configure gitlint to ignore specific commits or parts of a commit. One way to do this, is to by adding a gitline-ignore line to your commit message . 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\" . [ignore-by-title] # Match commit titles starting with Release regex=^Release(.*) ignore=title-max-length,body-min-length # ignore all rules by setting ignore to 'all' # ignore=all [ignore-by-body] # Match commits message bodies that have a line that contains 'release' regex=(.*)release(.*) ignore=all If you just want to ignore certain lines in a commit, you can do that using the ignore-body-lines rule. # Ignore all lines that start with 'Co-Authored-By' [ignore-body-lines] regex=^Co-Authored-By Warning When ignoring specific lines, gitlint will no longer be aware of them while applying other rules. This can sometimes be confusing for end-users, especially as line numbers of violations will typically no longer match line numbers in the original commit message. Make sure to educate your users accordingly. Note If you want to implement more complex ignore rules according to your own logic, you can do so using user-defined configuration rules .","title":"Ignoring commits"},{"location":"#named-rules","text":"Introduced in gitlint v0.14.0 Named rules allow you to have multiple of the same rules active at the same time, which allows you to enforce the same rule multiple times but with different options. Named rules are so-called because they require an additional unique identifier (i.e. the rule name ) during configuration. Warning Named rules is an advanced topic. It's easy to make mistakes by defining conflicting instances of the same rule. 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: # By adding the following section, you will add a second instance of the # title-must-not-contain-word (T5) rule (in addition to the one that is enabled # by default) with the name 'extra-words'. [title-must-not-contain-word:extra-words] words=foo,bar # So the generic form is # [<rule-id-or-name>:<your-chosen-name>] # Another example, referencing the rule type by id [T5:more-words] words=hur,dur # You can add as many additional rules and you can name them whatever you want # The only requirement is that names cannot contain whitespace or colons (:) [title-must-not-contain-word:This-Can_Be*Whatever$YouWant] words=wonderwoman,batman,power ranger When executing gitlint, you will see the violations from the default title-must-not-contain-word (T5) rule, as well as the violations caused by the additional Named Rules. $ 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\" 1: T5:extra-words Title contains the word 'bar' (case-insensitive): \"WIP: foo wonderwoman hur bar\" 1: T5:more-words Title contains the word 'hur' (case-insensitive): \"WIP: foo wonderwoman hur bar\" Named rules are further treated identical to all other rules in gitlint: You can reference them by their full name, when e.g. adding them to your ignore configuration # .gitlint file example [general] ignore=T5:more-words,title-must-not-contain-word:extra-words You can use them to instantiate multiple of the same user-defined rule You can configure them using any of the ways you can configure regular gitlint rules","title":"Named Rules"},{"location":"#exit-codes","text":"Gitlint uses the exit code as a simple way to indicate the number of violations found. Some exit codes are used to indicate special errors as indicated in the table below. Because of these special error codes and the fact that bash only supports exit codes between 0 and 255 , the maximum number of violations counted by the exit code is 252. Note that gitlint does not have a limit on the number of violations 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","title":"Exit codes"},{"location":"configuration/","text":"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: gitlint generate-config You can also use a different config file like so: gitlint --config myconfigfile.ini The block below shows a sample .gitlint file. Details about rule config options can be found on the Rules page, details about the [general] section can be found in the General Configuration section of this page. # 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 and squash commits. ignore-merge-commits=true ignore-revert-commits=true ignore-fixup-commits=true ignore-squash-commits=true # Ignore any data send 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 # 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/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 # 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: Commit specific config (e.g.: gitlint-ignore: all in the commit message) Configuration Rules (e.g.: ignore-by-title ) Commandline convenience flags (e.g.: -vv , --silent , --ignore ) Environment variables (e.g.: GITLINT_VERBOSITY=3 ) Commandline configuration flags (e.g.: -c title-max-length=123 ) Configuration file (local .gitlint file, or file specified using -C / --config ) 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 code to determine result. Default value gitlint version commandline flag environment variable False >= 0.1.0 --silent GITLINT_SILENT Examples # 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 # 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 # .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 # 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 #.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 # 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 # 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 #.gitlint [general] target=/home/joe/myrepo/ extra-path Path where gitlint looks for user-defined rules . Default value gitlint version commandline flag environment variable (empty) >= 0.8.0 --extra-path GITLINT_EXTRA_PATH Examples # 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 #.gitlint [general] extra-path=/home/joe/rules/ contrib Comma-separated list of Contrib rules to enable (by name or id). Default value gitlint version commandline flag environment variable (empty) >= 0.12.0 --contrib GITLINT_CONTRIB Examples # 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 #.gitlint [general] contrib=contrib-title-conventional-commits,CC1 staged 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 environment variable false >= 0.13.0 --staged GITLINT_STAGED Examples # CLI gitlint --staged gitlint -c general.staged=true # different way of doing the same GITLINT_STAGED=1 gitlint # using env variable #.gitlint [general] staged=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 # CLI gitlint --ignore-stdin gitlint -c general.ignore-stdin=true # different way of doing the same GITLINT_IGNORE_STDIN=1 gitlint # using env variable #.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 # CLI gitlint -c general.ignore-merge-commits=false #.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 # CLI gitlint -c general.ignore-revert-commits=false #.gitlint [general] ignore-revert-commits=false ignore-fixup-commits Whether or not to ignore fixup commits. Default value gitlint version commandline flag environment variable true >= 0.9.0 Not Available Not Available Examples # CLI gitlint -c general.ignore-fixup-commits=false #.gitlint [general] ignore-fixup-commits=false ignore-squash-commits Whether or not to ignore squash commits. Default value gitlint version commandline flag environment variable true >= 0.9.0 Not Available Not Available Examples # CLI gitlint -c general.ignore-squash-commits=false #.gitlint [general] ignore-squash-commits=false","title":"Configuration"},{"location":"configuration/#configuration","text":"Gitlint can be configured through different means.","title":"Configuration"},{"location":"configuration/#the-gitlint-file","text":"You can modify gitlint's behavior by adding a .gitlint file to your git repository. Generate a default .gitlint config file by running: gitlint generate-config You can also use a different config file like so: gitlint --config myconfigfile.ini The block below shows a sample .gitlint file. Details about rule config options can be found on the Rules page, details about the [general] section can be found in the General Configuration section of this page. # 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-punctuatio