git/gitlint
1
0
Fork 0
Code Issues Activity

Merging upstream version 0.16.0.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-13 06:05:35 +01:00
parent 40df5416c1
commit 72676ec535
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
56 changed files with 615 additions and 161 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/configuration.md
View file

@ -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.

4
docs/contributing.md
View file

@ -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
```

BIN
docs/images/readme-gitlint.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 340 KiB

52
docs/index.md
View file

@ -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

31
docs/rules.md
View file

@ -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
```