From 6f442e774b9236c999f36c2d7af17640f49bff99 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Tue, 9 Apr 2024 15:38:02 +0200 Subject: Adding upstream version 0.19.1. Signed-off-by: Daniel Baumann --- docs/configuration.md | 628 +++++ docs/contrib_rules.md | 83 + docs/contributing.md | 213 ++ docs/demos/asciicinema.json | 3798 +++++++++++++++++++++++++++++++ docs/demos/scenario.txt | 75 + docs/extra.css | 12 + docs/extra.js | 5 + docs/images/RuleViolation.png | Bin 0 -> 27806 bytes docs/images/RuleViolations.graffle | Bin 0 -> 3291 bytes docs/images/dev-container.png | Bin 0 -> 212226 bytes docs/images/gitlint-packages.drawio.svg | 351 +++ docs/images/gitlint-packages.png | Bin 0 -> 51975 bytes docs/images/readme-gitlint.png | Bin 0 -> 348007 bytes docs/index.md | 506 ++++ docs/rules.md | 461 ++++ docs/user_defined_rules.md | 415 ++++ 16 files changed, 6547 insertions(+) create mode 100644 docs/configuration.md create mode 100644 docs/contrib_rules.md create mode 100644 docs/contributing.md create mode 100644 docs/demos/asciicinema.json create mode 100644 docs/demos/scenario.txt create mode 100644 docs/extra.css create mode 100644 docs/extra.js create mode 100644 docs/images/RuleViolation.png create mode 100644 docs/images/RuleViolations.graffle create mode 100644 docs/images/dev-container.png create mode 100644 docs/images/gitlint-packages.drawio.svg create mode 100644 docs/images/gitlint-packages.png create mode 100644 docs/images/readme-gitlint.png create mode 100644 docs/index.md create mode 100644 docs/rules.md create mode 100644 docs/user_defined_rules.md (limited to 'docs') 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 .