diff options
Diffstat (limited to 'docs/configuration.md')
| -rw-r--r-- | docs/configuration.md | 628 |
1 files changed, 628 insertions, 0 deletions
diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..af49d7c --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,628 @@ +# 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 +``` + +*If you don't have any custom regex specified, gitlint will not log a warning and no action is needed.* + +**To remove the warning:** + +1. Review your regex in the rules gitlint warned for and ensure it's still accurate when using [`re.search()` semantics](https://docs.python.org/3/library/re.html#search-vs-match). +2. Enable `regex-style-search` in your `.gitlint` file (or using [any other way to configure gitlint](http://127.0.0.1:8000/gitlint/configuration/)): + +```ini +[general] +regex-style-search=true +``` + +#### More context +Python offers [two different primitive operations based on regular expressions](https://docs.python.org/3/library/re.html#search-vs-match): +`re.match()` checks for a match only at the beginning of the string, while `re.search()` checks for a match anywhere +in the string. + + + +Most rules in gitlint already use `re.search()` instead of `re.match()`, but there's a few notable exceptions that +use `re.match()`, which can lead to unexpected matching behavior. + +- M1 - author-valid-email +- I1 - ignore-by-title +- I2 - ignore-by-body +- I3 - ignore-body-lines +- I4 - ignore-by-author-name + +The `regex-style-search` option is meant to fix this inconsistency. Setting it to `true` will force the above rules to +use `re.search()` instead of `re.match()`. For detailed context, see [issue #254](https://github.com/jorisroovers/gitlint/issues/254). + + +#### Examples +```sh +# CLI +gitlint -c general.regex-style-search=true +``` +```ini +#.gitlint +[general] +regex-style-search=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 +```sh +# CLI +gitlint --ignore-stdin +gitlint -c general.ignore-stdin=true # different way of doing the same +GITLINT_IGNORE_STDIN=1 gitlint # using env variable +``` +```ini +#.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 +```sh +# CLI +gitlint -c general.ignore-merge-commits=false +``` +```ini +#.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 +```sh +# CLI +gitlint -c general.ignore-revert-commits=false +``` +```ini +#.gitlint +[general] +ignore-revert-commits=false +``` +------------------------------------------------------------------------------------------------------------------------ + +### 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 | environment variable | +| ------------- | --------------- | ---------------- | -------------------- | +| true | >= 0.9.0 | Not Available | Not Available | + +#### Examples +```sh +# CLI +gitlint -c general.ignore-fixup-commits=false +``` +```ini +#.gitlint +[general] +ignore-fixup-commits=false +``` +------------------------------------------------------------------------------------------------------------------------ + +### ignore-fixup-amend-commits + +Whether or not to ignore [fixup=amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt) commits. + +| Default value | gitlint version | commandline flag | environment variable | +| ------------- | --------------- | ---------------- | -------------------- | +| true | >= 0.18.0 | Not Available | Not Available | + +#### Examples +```sh +# CLI +gitlint -c general.ignore-fixup-amend-commits=false +``` +```ini +#.gitlint +[general] +ignore-fixup-amend-commits=false +``` +------------------------------------------------------------------------------------------------------------------------ + +### 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 | environment variable | +| ------------- | --------------- | ---------------- | -------------------- | +| true | >= 0.9.0 | Not Available | Not Available | + +#### Examples +```sh +# CLI +gitlint -c general.ignore-squash-commits=false +``` +```ini +#.gitlint +[general] +ignore-squash-commits=false +```
\ No newline at end of file |