git/gitlint
1
0
Fork 0
Code Issues Activity

Merging upstream version 0.18.0.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-13 06:06:24 +01:00
parent 0453b640a2
commit 129d2ce1fc
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
118 changed files with 4146 additions and 2087 deletions
Download patch file Download diff file Expand all files Collapse all files

118
docs/index.md
View file

@ -22,11 +22,11 @@ Great for use as a [commit-msg git hook](#using-gitlint-as-a-commit-msg-hook) or
- **Easily integrated**: Gitlint is designed to work [with your own scripts or CI system](#using-gitlint-in-a-ci-environment).
- **Sane defaults:** Many of gitlint's validations are based on
[well-known](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html),
[community](http://addamhardy.com/2013/06/05/good-commit-messages-and-enforcing-them-with-git-hooks.html),
[community](https://addamhardy.com/2013-06-05-good-commit-messages-and-enforcing-them-with-git-hooks),
[standards](http://chris.beams.io/posts/git-commit/), others are based on checks that we've found
useful throughout the years.
- **Easily configurable:** Gitlint has sane defaults, but [you can also easily customize it to your own liking](configuration.md).
- **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules).
- **Community contributed rules**: Conventions that are common but not universal [can be selectively enabled](contrib_rules.md).
- **User-defined rules:** Want to do more then what gitlint offers out of the box? Write your own [user defined rules](user_defined_rules.md).
- **Full unicode support:** Lint your Russian, Chinese or Emoji commit messages with ease!
- **Production-ready:** Gitlint checks a lot of the boxes you're looking for: actively maintained, high unit test coverage, integration tests,
@ -38,6 +38,10 @@ useful throughout the years.
# Pip is recommended to install the latest version
pip install gitlint
# Alternative: by default, gitlint is installed with pinned dependencies.
# To install gitlint with looser dependency requirements, only install gitlint-core.
pip install gitlint-core
# Community maintained packages:
brew install gitlint # Homebrew (macOS)
sudo port install gitlint # Macports (macOS)
@ -81,6 +85,19 @@ $ cat examples/commit-message-2 | gitlint
!!! note
The returned exit code equals the number of errors found. [Some exit codes are special](index.md#exit-codes).
### Shell completion
```sh
# Bash: add to ~/.bashrc
eval "$(_GITLINT_COMPLETE=bash_source gitlint)"
# Zsh: add to ~/.zshrc
eval "$(_GITLINT_COMPLETE=zsh_source gitlint)"
# Fish: add to ~/.config/fish/completions/foo-bar.fish
eval (env _GITLINT_COMPLETE=fish_source gitlint)
```
## Configuration
For in-depth documentation of general and rule-specific configuration options, have a look at the [Configuration](configuration.md) and [Rules](rules.md) pages.
@ -93,7 +110,7 @@ Short example `.gitlint` file ([full reference](configuration.md)):
# their id or by their full name
ignore=body-is-missing,T3
# Ignore any data send to gitlint via stdin
# Ignore any data sent to gitlint via stdin
ignore-stdin=true
# Configure title-max-length rule, set title length to 80 (72 = default)
@ -136,7 +153,8 @@ Options:
(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]
--commits TEXT The range of commits (refspec or comma-separated
hashes) to lint. [default: HEAD]
-e, --extra-path PATH Path to a directory or python module with extra
user-defined rules
--ignore TEXT Ignore rules (comma-separated by id or name).
@ -145,8 +163,9 @@ Options:
--msg-filename FILENAME Path to a file containing a commit-msg.
--ignore-stdin Ignore any stdin data. Useful for running in CI
server.
--staged Read staged commit meta-info from the local
repository.
--staged Attempt smart guesses about meta info (like
author name, email, branch, changed files, etc)
for staged commits.
--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]
@ -218,7 +237,7 @@ In case you want to change gitlint's behavior, you should either use a `.gitlint
your `.pre-commit-config.yaml` file like so:
```yaml
- repo: https://github.com/jorisroovers/gitlint
rev: # Fill in a tag / sha here
rev: # Fill in a tag / sha here (e.g. v0.18.0)
hooks:
- id: gitlint
args: [--contrib=CT1, --msg-filename]
@ -229,6 +248,36 @@ your `.pre-commit-config.yaml` file like so:
You need to add `--msg-filename` at the end of your custom `args` list as the gitlint-hook will fail otherwise.
### gitlint and pre-commit in CI
gitlint also supports a `gitlint-ci` pre-commit hook that can be used in CI environments.
Configure it like so:
```yaml
- repo: https://github.com/jorisroovers/gitlint
rev: # insert ref, e.g. v0.18.0
hooks:
- id: gitlint # this is the regular commit-msg hook
- id: gitlint-ci # hook for CI environments
```
And invoke it in your CI environment like this:
```sh
pre-commit run --hook-stage manual gitlint-ci
```
By default this will only lint the latest commit.
If you want to lint more commits you can modify the `gitlint-ci` hook like so:
```yaml
- repo: https://github.com/jorisroovers/gitlint
rev: v0.17.0
hooks:
- id: gitlint
- id: gitlint-ci
args: [--debug, --commits, mybranch] # enable debug mode, lint all commits in mybranch
```
## Using gitlint in a CI environment
By default, when just running `gitlint` without additional parameters, gitlint lints the last commit in the current
working directory.
@ -248,33 +297,48 @@ 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 specific commits
## Linting specific commits or branches
Gitlint allows users to lint a specific commit:
Gitlint can lint specific commits using `--commit`:
```sh
gitlint --commit 019cf40580a471a3958d3c346aa8bfd265fe5e16
gitlint --commit 019cf40 # short SHAs work too
gitlint --commit 019cf40 # short SHAs work too
gitlint --commit HEAD~2 # as do special references
gitlint --commit mybranch # lint latest commit on a branch
```
You can also lint multiple commits at once like so:
You can also lint multiple commits using `--commits` (plural):
```sh
# Lint a specific commit range:
gitlint --commits "019cf40...d6bc75a"
# You can also use git's special references:
# Lint all commits on a branch
gitlint --commits mybranch
# Lint all commits that are different between a branch and your main branch
gitlint --commits "main..mybranch"
# Use git's special references
gitlint --commits "origin..HEAD"
# You can also pass multiple, comma separated commit hashes:
gitlint --commits 019cf40,c50eb150,d6bc75a
# These can include special references as well
gitlint --commits HEAD~1,mybranch-name,origin/main,d6bc75a
```
The `--commits` flag takes a **single** refspec argument or commit range. Basically, any range that is understood
by [git rev-list](https://git-scm.com/docs/git-rev-list) as a single argument will work.
Alternatively, you can pass `--commits` a comma-separated list of commit hashes (both short and full-length SHAs work,
as well as special references such as `HEAD` and branch names).
Gitlint will treat these as pointers to **single** commits and lint these in the order you passed.
For cases where the `--commits` option doesn't provide the flexibility you need, you can always use a simple shell
script to lint an arbitrary set of commits, like shown in the example below.
```sh
#!/bin/sh
for commit in $(git rev-list master); do
for commit in $(git rev-list my-branch); do
echo "Commit $commit"
gitlint --commit $commit
echo "--------"
@ -283,14 +347,14 @@ done
!!! note
One downside to this approach is that you invoke gitlint once per commit vs. once per set of commits.
This means you'll incur the gitlint startup time once per commit, making this approach rather slow if you want to
This means you'll incur the gitlint startup time once per commit, making it rather slow if you want to
lint a large set of commits. Always use `--commits` if you can to avoid this performance penalty.
## Merge, fixup, squash and revert commits
_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash) and v0.13.0 (revert)_
_Introduced in gitlint v0.7.0 (merge), v0.9.0 (fixup, squash), v0.13.0 (revert) and v0.18.0 (fixup=amend)_
**Gitlint ignores merge, revert, fixup and squash commits by default.**
**Gitlint ignores merge, revert, fixup, and squash commits by default.**
For merge and revert commits, the rationale for ignoring them is
that most users keep git's default messages for these commits (i.e *Merge/Revert "[original commit message]"*).
@ -300,14 +364,14 @@ For example, a common case is that *"Merge:"* being auto-prepended triggers a
[title-max-length](rules.md#t1-title-max-length) violation. Most users don't want this, so we disable linting
on Merge and Revert commits by default.
For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) commits, the rationale is that these are temporary
For [squash](https://git-scm.com/docs/git-commit#git-commit---squashltcommitgt) and [fixup](https://git-scm.com/docs/git-commit#git-commit---fixupltcommitgt) (including [fixup=amend](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)) commits, the rationale is that these are temporary
commits that will be squashed into a different commit, and hence the commit messages for these commits are very
short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"* or
*"squash!"* to your commit message, certain gitlint rules might be violated
short-lived and not intended to make it into the final commit history. In addition, by prepending *"fixup!"*,
*"amend!"* or *"squash!"* to your commit message, certain gitlint rules might be violated
(e.g. [title-max-length](rules.md#t1-title-max-length)) which is often undesirable.
In case you *do* want to lint these commit messages, you can disable this behavior by setting the
general `ignore-merge-commits`, `ignore-revert-commits`, `ignore-fixup-commits` or
general `ignore-merge-commits`, `ignore-revert-commits`, `ignore-fixup-commits`, `ignore-fixup-amend-commits` or
`ignore-squash-commits` option to `false`
[using one of the various ways to configure gitlint](configuration.md).
@ -374,7 +438,7 @@ additional unique identifier (i.e. the rule *name*) during configuration.
For example, by defining 2 `body-max-line-length` rules with different `line-length` options, you obviously create
a conflicting situation. Gitlint does not do any resolution of such conflicts, it's up to you to make sure
any configuration is non-conflicting. So caution advised!
Defining a named rule is easy, for example using your `.gitlint` file:
```ini
@ -400,7 +464,7 @@ When executing gitlint, you will see the violations from the default `title-must
the violations caused by the additional Named Rules.
```sh
$ gitlint
$ gitlint
1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:This-Can_Be*Whatever$YouWant Title contains the word 'wonderwoman' (case-insensitive): "WIP: foo wonderwoman hur bar"
1: T5:extra-words Title contains the word 'foo' (case-insensitive): "WIP: foo wonderwoman hur bar"
@ -431,8 +495,8 @@ of violations counted by the exit code is 252. Note that gitlint does not have a
it can detect, it will just always return with exit code 252 when the number of violations is greater than or equal
to 252.
Exit Code | Description
-----------|------------------------------------------------------------
253 | Wrong invocation of the `gitlint` command.
254 | Something went wrong when invoking git.
255 | Invalid gitlint configuration
| Exit Code | Description |
| --------- | ------------------------------------------ |
| 253 | Wrong invocation of the `gitlint` command. |
| 254 | Something went wrong when invoking git. |
| 255 | Invalid gitlint configuration |