diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2021-10-13 05:34:57 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2021-10-13 05:34:57 +0000 |
commit | e2d38cd54491535f409372393baeed787c77388d (patch) | |
tree | e9f823c384ee487d30de5ae84c8d3755f6974baa /docs | |
parent | Releasing debian version 0.15.1-3. (diff) | |
download | gitlint-e2d38cd54491535f409372393baeed787c77388d.tar.xz gitlint-e2d38cd54491535f409372393baeed787c77388d.zip |
Merging upstream version 0.16.0.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/configuration.md | 41 | ||||
-rw-r--r-- | docs/contributing.md | 4 | ||||
-rw-r--r-- | docs/images/readme-gitlint.png | bin | 0 -> 348007 bytes | |||
-rw-r--r-- | docs/index.md | 52 | ||||
-rw-r--r-- | docs/rules.md | 31 |
5 files changed, 103 insertions, 25 deletions
diff --git a/docs/configuration.md b/docs/configuration.md index 50c4e63..226ba8a 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -52,6 +52,12 @@ ignore-stdin=true # 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 + # Enable debug mode (prints more output). Disabled by default. debug=true @@ -128,7 +134,7 @@ 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(.*) +regex=(.*)release(.*) # # Ignore certain rules, you can reference them by their id or by their full name # Use 'all' to ignore all rules @@ -139,6 +145,15 @@ ignore=T1,body-min-length # 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. @@ -363,6 +378,30 @@ GITLINT_STAGED=1 gitlint # using env variable 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 +``` + ### ignore-stdin Ignore any stdin data. Sometimes useful when running gitlint in a CI server. diff --git a/docs/contributing.md b/docs/contributing.md index e58378c..d39f9e1 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -44,7 +44,9 @@ vagrant ssh Or you can choose to use your local environment: ```sh -virtualenv .venv +python -m venv .venv +. .venv/bin/activate +pip install --upgrade pip pip install -r requirements.txt -r test-requirements.txt -r doc-requirements.txt python setup.py develop ``` diff --git a/docs/images/readme-gitlint.png b/docs/images/readme-gitlint.png Binary files differnew file mode 100644 index 0000000..516c915 --- /dev/null +++ b/docs/images/readme-gitlint.png diff --git a/docs/index.md b/docs/index.md index 5b371bf..98b72de 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,12 +38,11 @@ useful throughout the years. # 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 +# Community maintained packages: +brew install gitlint # Homebrew (macOS) +sudo port install gitlint # Macports (macOS) +apt-get install gitlint # Ubuntu +# Other package managers, see https://repology.org/project/gitlint/versions # Docker: https://hub.docker.com/r/jorisroovers/gitlint docker run --ulimit nofile=1024 -v $(pwd):/repo jorisroovers/gitlint @@ -134,8 +133,9 @@ Options: 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. + (e.g.: -c T1.line-length=80). Flag can be + used multiple times to set multiple config values. + --commit TEXT Hash (SHA) of specific commit to lint. --commits TEXT The range of commits to lint. [default: HEAD] -e, --extra-path PATH Path to a directory or python module with extra user-defined rules @@ -147,10 +147,11 @@ Options: 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. + --fail-without-commits Hard fail when the target commit range is empty. + -v, --verbose Verbosity, more v's for more verbose output + (e.g.: -v, -vv, -vvv). [default: -vvv] + -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. @@ -159,6 +160,7 @@ 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] + run-hook Runs the gitlint commit-msg hook. uninstall-hook Uninstall gitlint commit-msg hook. When no COMMAND is specified, gitlint defaults to 'gitlint lint'. @@ -246,19 +248,21 @@ 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 +## Linting specific commits -_Introduced in gitlint v0.9.0 (experimental in v0.8.0)_ +Gitlint allows users to lint a specific commit: +```sh +gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16 +gitlint --commit 019cf40 # short SHAs work too +``` -Gitlint allows users to lint a number of commits at once like so: +You can also lint multiple commits at once like so: ```sh # 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 @@ -271,9 +275,8 @@ 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 "Commit $commit" + gitlint --commit $commit echo "--------" done ``` @@ -309,7 +312,6 @@ general `ignore-merge-commits`, `ignore-revert-commits`, `ignore-fixup-commits` [using one of the various ways to configure gitlint](configuration.md). ## Ignoring commits -_Introduced in gitlint v0.10.0_ You can configure gitlint to ignore specific commits or parts of a commit. @@ -317,8 +319,7 @@ One way to do this, is to by [adding a gitline-ignore line to your commit messag 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"*. +Here's a few examples snippets from a `.gitlint` file: ```ini [ignore-by-title] @@ -332,6 +333,11 @@ ignore=title-max-length,body-min-length # Match commits message bodies that have a line that contains 'release' regex=(.*)release(.*) ignore=all + +[ignore-by-author-name] +# Match commits by author name (e.g. ignore all rules when a commit is made by dependabot) +regex=dependabot +ignore=all ``` If you just want to ignore certain lines in a commit, you can do that using the diff --git a/docs/rules.md b/docs/rules.md index 9779c54..eb4b65e 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -30,6 +30,8 @@ M1 | author-valid-email | >= 0.9.0 | Author email address m I1 | ignore-by-title | >= 0.10.0 | Ignore a commit based on matching its title I2 | ignore-by-body | >= 0.10.0 | Ignore a commit based on matching its body I3 | ignore-body-lines | >= 0.14.0 | Ignore certain lines in a commit body that match a regex +I4 | ignore-by-author-name | >= 0.16.0 | Ignore a commit based on matching its author name + ## T1: title-max-length @@ -405,3 +407,32 @@ regex=(^Co-Authored-By)|(^Signed-off-by) [ignore-body-lines] regex=(.*)foobar(.*) ``` + +## I4: ignore-by-author-name + +ID | Name | gitlint version | Description +------|---------------------------|-----------------|------------------------------------------- +I4 | ignore-by-author-name | >= 0.16.0 | Ignore a commit based on matching its author name. + +### Options + +Name | gitlint version | Default | Description +----------------------|-------------------|------------------------------|---------------------------------- +regex | >= 0.16.0 | None | [Python regex](https://docs.python.org/library/re.html) to match against the commit author name. On match, the commit will be ignored. +ignore | >= 0.16.0 | all | Comma-separated list of rule names or ids to ignore when this rule is matched. + +### Examples + +#### .gitlint + +```ini +# Ignore all commits authored by dependabot +[ignore-by-author-name] +regex=dependabot + +# For commits made by anyone with "[bot]" in their name, ignore +# rules T1, body-min-length and B6 +[ignore-by-author-name] +regex=(.*)\[bot\](.*) +ignore=T1,body-min-length,B6 +```
\ No newline at end of file |