diff options
Diffstat (limited to 'docs/configuration.md')
| -rw-r--r-- | docs/configuration.md | 296 |
1 files changed, 161 insertions, 135 deletions
diff --git a/docs/configuration.md b/docs/configuration.md index 641b361..78224c1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,21 +1,21 @@ # Configuration Gitlint can be configured through different means. -# Config files # -You can modify gitlint's behavior by adding a ```.gitlint``` file to your git repository. +## The .gitlint file +You can modify gitlint's behavior by adding a `.gitlint` file to your git repository. -Generate a default ```.gitlint``` config file by running: -```bash +Generate a default `.gitlint` config file by running: +```sh gitlint generate-config ``` You can also use a different config file like so: -```bash +```sh gitlint --config myconfigfile.ini ``` -The block below shows a sample ```.gitlint``` file. Details about rule config options can be found on the -[Rules](rules.md) page, details about the ```[general]``` section can be found in the +The block below shows a sample `.gitlint` file. Details about rule config options can be found on the +[Rules](rules.md) page, details about the `[general]` section can be found in the [General Configuration](configuration.md#general-configuration) section of this page. ```ini @@ -25,7 +25,7 @@ The block below shows a sample ```.gitlint``` file. Details about rule config op # 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 be written as "[B1]". Full section names are +# 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/ # @@ -68,6 +68,11 @@ extra-path=examples/ [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" @@ -99,10 +104,15 @@ ignore-merge-commits=false # it in the commit message. files=gitlint/rules.py,README.md +[body-match-regex] +# python-style regex that the commit-msg body must match. +# E.g. body must end in My-Commit-Tag: foo +regex=My-Commit-Tag: foo$ + [author-valid-email] # python like regex (https://docs.python.org/2/library/re.html) that the # commit author email address should be matched to -# For example, use the following regex if you only want to allow email addresses from foo.com +# 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] @@ -123,6 +133,11 @@ ignore=T1,body-min-length # Use 'all' to ignore all rules ignore=T1,body-min-length +[ignore-body-lines] +# Ignore certain lines in a commit body that match a regex. +# E.g. Ignore all lines that start with 'Co-Authored-By' +regex=^Co-Authored-By + # This is a contrib rule - a community contributed rule. These are disabled by default. # You need to explicitly enable them one-by-one by adding them to the "contrib" option # under [general] section above. @@ -131,20 +146,20 @@ ignore=T1,body-min-length types = bugfix,user-story,epic ``` -# Commandline config # +## Commandline config -You can also use one or more ```-c``` flags like so: +You can also use one or more `-c` flags like so: ``` $ gitlint -c general.verbosity=2 -c title-max-length.line-length=80 -c B1.line-length=100 ``` -The generic config flag format is ```-c <rule>.<option>=<value>``` and supports all the same rules and options which -you can also use in a ```.gitlint``` config file. +The generic config flag format is `-c <rule>.<option>=<value>` and supports all the same rules and options which +you can also use in a `.gitlint` config file. -# Commit specific config # +## Commit specific config You can also configure gitlint by adding specific lines to your commit message. -For now, we only support ignoring commits by adding ```gitlint-ignore: all``` to the commit +For now, we only support ignoring commits by adding `gitlint-ignore: all` to the commit message like so: ``` @@ -154,7 +169,7 @@ I want gitlint to ignore this entire commit message. gitlint-ignore: all ``` -```gitlint-ignore: all``` can occur on any line, as long as it is at the start of the line. +`gitlint-ignore: all` can occur on any line, as long as it is at the start of the line. You can also specify specific rules to be ignored as follows: ``` @@ -166,44 +181,46 @@ gitlint-ignore: T1, body-hard-tab -# Configuration precedence # +## Configuration precedence gitlint configuration is applied in the following order of precedence: -1. Commit specific config (e.g.: ```gitlint-ignore: all``` in the commit message) +1. Commit specific config (e.g.: `gitlint-ignore: all` in the commit message) 2. Configuration Rules (e.g.: [ignore-by-title](/rules/#i1-ignore-by-title)) -3. Commandline convenience flags (e.g.: ```-vv```, ```--silent```, ```--ignore```) -4. Commandline configuration flags (e.g.: ```-c title-max-length=123```) -5. Configuration file (local ```.gitlint``` file, or file specified using ```-C```/```--config```) -6. Default gitlint config +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 +## General Options Below we outline all configuration options that modify gitlint's overall behavior. These options can be specified -using commandline flags or in ```[general]``` section in a ```.gitlint``` configuration file. +using commandline flags or in `[general]` section in a `.gitlint` configuration file. -## silent +### silent Enable silent mode (no output). Use [exit](index.md#exit-codes) code to determine result. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - false | >= 0.1.0 | ```--silent``` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- +`False` | >= 0.1.0 | `--silent` | `GITLINT_SILENT` -### Examples +#### Examples ```sh # CLI gitlint --silent +GITLINT_SILENT=1 gitlint # using env variable ``` -## verbosity +### verbosity Amount of output gitlint will show when printing errors. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - 3 | >= 0.1.0 | `-v` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- +3 | >= 0.1.0 | `-v` | `GITLINT_VERBOSITY` -### Examples +#### Examples ```sh # CLI gitlint -vvv # default (level 3) @@ -212,221 +229,230 @@ 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 +# .gitlint [general] verbosity=2 ``` -## ignore-merge-commits +### ignore -Whether or not to ignore merge commits. +Comma separated list of rules to ignore (by name or id). -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - true | >= 0.7.0 | Not Available +Default value | gitlint version | commandline flag | environment variable +---------------------------|------------------|-------------------|----------------------- + [] (=empty list) | >= 0.1.0 | `--ignore` | `GITLINT_IGNORE` -### Examples +#### Examples ```sh # CLI -gitlint -c general.ignore-merge-commits=false +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-merge-commits=false +ignore=T1,body-min-length ``` -## ignore-revert-commits +### debug -Whether or not to ignore revert commits. +Enable debugging output. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - true | >= 0.13.0 | Not Available +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + false | >= 0.7.1 | `--debug` | `GITLINT_DEBUG` -### Examples +#### Examples ```sh # CLI -gitlint -c general.ignore-revert-commits=false -``` -```ini -#.gitlint -[general] -ignore-revert-commits=false +gitlint --debug +GITLINT_DEBUG=1 gitlint # using env variable +# --debug is special, the following does NOT work +# gitlint -c general.debug=true ``` -## ignore-fixup-commits +### target -Whether or not to ignore [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits. +Target git repository gitlint should be linting against. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - true | >= 0.9.0 | Not Available +Default value | gitlint version | commandline flag | environment variable +---------------------------|------------------|-------------------|----------------------- +(empty) | >= 0.8.0 | `--target` | `GITLINT_TARGET` -### Examples +#### Examples ```sh # CLI -gitlint -c general.ignore-fixup-commits=false +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] -ignore-fixup-commits=false +target=/home/joe/myrepo/ ``` -## ignore-squash-commits +### extra-path -Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits. +Path where gitlint looks for [user-defined rules](user_defined_rules.md). -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - true | >= 0.9.0 | Not Available +Default value | gitlint version | commandline flag | environment variable +---------------------------|------------------|-------------------|----------------------- + (empty) | >= 0.8.0 | `--extra-path` | `GITLINT_EXTRA_PATH` -### Examples +#### Examples ```sh # CLI -gitlint -c general.ignore-squash-commits=false +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] -ignore-squash-commits=false +extra-path=/home/joe/rules/ ``` -## ignore +### contrib -Comma separated list of rules to ignore (by name or id). +Comma-separated list of [Contrib rules](contrib_rules) to enable (by name or id). -Default value | gitlint version | commandline flag ----------------------------|------------------|------------------- - [] (=empty list) | >= 0.1.0 | `--ignore` +Default value | gitlint version | commandline flag | environment variable +---------------------------|------------------|-------------------|----------------------- + (empty) | >= 0.12.0 | `--contrib` | `GITLINT_CONTRIB` -### Examples +#### 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 --contrib=contrib-title-conventional-commits,CC1 +gitlint -c general.contrib=contrib-title-conventional-commits,CC1 # different way of doing the same +GITLINT_CONTRIB=contrib-title-conventional-commits,CC1 gitlint # using env variable ``` ```ini #.gitlint [general] -ignore=T1,body-min-length +contrib=contrib-title-conventional-commits,CC1 ``` -## debug +### staged -Enable debugging output. +Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or `--commit-msg`. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - false | >= 0.7.1 | `--debug` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + false | >= 0.13.0 | `--staged` | `GITLINT_STAGED` -### Examples +#### Examples ```sh # CLI -gitlint --debug -# --debug is special, the following does NOT work -# gitlint -c general.debug=true +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 ``` -## target +### ignore-stdin -Target git repository gitlint should be linting against. +Ignore any stdin data. Sometimes useful when running gitlint in a CI server. -Default value | gitlint version | commandline flag ----------------------------|------------------|------------------- - (empty) | >= 0.8.0 | `--target` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + false | >= 0.12.0 | `--ignore-stdin` | `GITLINT_IGNORE_STDIN` -### Examples +#### Examples ```sh # CLI -gitlint --target=/home/joe/myrepo/ -gitlint -c general.target=/home/joe/myrepo/ # different way of doing the same +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] -target=/home/joe/myrepo/ +ignore-stdin=true ``` -## extra-path +### ignore-merge-commits -Path where gitlint looks for [user-defined rules](user_defined_rules.md). +Whether or not to ignore merge commits. -Default value | gitlint version | commandline flag ----------------------------|------------------|------------------- - (empty) | >= 0.8.0 | `--extra-path` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + true | >= 0.7.0 | Not Available | Not Available -### Examples +#### Examples ```sh # CLI -gitlint --extra-path=/home/joe/rules/ -gitlint -c general.extra-path=/home/joe/rules/ # different way of doing the same +gitlint -c general.ignore-merge-commits=false ``` ```ini #.gitlint [general] -extra-path=/home/joe/rules/ +ignore-merge-commits=false ``` -## contrib +### ignore-revert-commits -[Contrib rules](contrib_rules) to enable. +Whether or not to ignore revert commits. -Default value | gitlint version | commandline flag ----------------------------|------------------|------------------- - (empty) | >= 0.12.0 | `--contrib` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + true | >= 0.13.0 | Not Available | Not Available -### Examples +#### Examples ```sh # CLI -gitlint --contrib=contrib-title-conventional-commits,CC1 -gitlint -c general.contrib=contrib-title-conventional-commits,CC1 # different way of doing the same +gitlint -c general.ignore-revert-commits=false ``` ```ini #.gitlint [general] -contrib=contrib-title-conventional-commits,CC1 +ignore-revert-commits=false ``` -## ignore-stdin -Ignore any stdin data. Sometimes useful when running gitlint in a CI server. +### 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 ----------------|------------------|------------------- - false | >= 0.12.0 | `--ignore-stdin` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + true | >= 0.9.0 | Not Available | Not Available -### Examples +#### Examples ```sh # CLI -gitlint --ignore-stdin -gitlint -c general.ignore-stdin=true # different way of doing the same +gitlint -c general.ignore-fixup-commits=false ``` ```ini #.gitlint [general] -ignore-stdin=true +ignore-fixup-commits=false ``` -## staged +### ignore-squash-commits -Fetch additional meta-data from the local `repository when manually passing a commit message to gitlint via stdin or ```--commit-msg```. +Whether or not to ignore [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) commits. -Default value | gitlint version | commandline flag ----------------|------------------|------------------- - false | >= 0.13.0 | `--staged` +Default value | gitlint version | commandline flag | environment variable +---------------|------------------|-------------------|----------------------- + true | >= 0.9.0 | Not Available | Not Available -### Examples +#### Examples ```sh # CLI -gitlint --staged -gitlint -c general.staged=true # different way of doing the same +gitlint -c general.ignore-squash-commits=false ``` ```ini #.gitlint [general] -staged=true +ignore-squash-commits=false ```
\ No newline at end of file |