83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# Using Contrib Rules
|
|
|
|
_Introduced in gitlint v0.12.0_
|
|
|
|
Contrib rules are community-**contrib**uted rules that are disabled by default, but can be enabled through configuration.
|
|
|
|
Contrib rules are meant to augment default gitlint behavior by providing users with rules for common use-cases without
|
|
forcing these rules on all gitlint users. This also means that users don't have to
|
|
re-implement these commonly used rules themselves as [user-defined](user_defined_rules.md) rules.
|
|
|
|
To enable certain contrib rules, you can use the `--contrib` flag.
|
|
```sh
|
|
$ cat examples/commit-message-1 | gitlint --contrib contrib-title-conventional-commits,CC1
|
|
1: CC1 Body does not contain a 'Signed-off-by' line
|
|
1: CL1 Title does not start with one of fix, feat, chore, docs, style, refactor, perf, test: "WIP: This is the title of a commit message."
|
|
|
|
# These are the default violations
|
|
1: T3 Title has trailing punctuation (.): "WIP: This is the title of a commit message."
|
|
1: T5 Title contains the word 'WIP' (case-insensitive): "WIP: This is the title of a commit message."
|
|
2: B4 Second line is not empty: "The second line should typically be empty"
|
|
3: B1 Line exceeds max length (123>80): "Lines typically need to have a max length, meaning that they can't exceed a preset number of characters, usually 80 or 120."
|
|
```
|
|
|
|
Same thing using a `.gitlint` file:
|
|
|
|
```ini
|
|
[general]
|
|
# You HAVE to add the rule here to enable it, only configuring (such as below)
|
|
# does NOT enable it.
|
|
contrib=contrib-title-conventional-commits,CC1
|
|
|
|
|
|
[contrib-title-conventional-commits]
|
|
# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
|
|
types = bugfix,user-story,epic
|
|
```
|
|
|
|
You can also configure contrib rules using [any of the other ways to configure gitlint](configuration.md).
|
|
|
|
## Available Contrib Rules
|
|
|
|
ID | Name | gitlint version | Description
|
|
------|-------------------------------------|------------------ |-------------------------------------------
|
|
CT1 | contrib-title-conventional-commits | >= 0.12.0 | Enforces [Conventional Commits](https://www.conventionalcommits.org/) commit message style on the title.
|
|
CC1 | contrib-body-requires-signed-off-by | >= 0.12.0 | Commit body must contain a `Signed-off-by` line.
|
|
CC2 | contrib-disallow-cleanup-commits | >= 0.18.0 | Commit title must not contain `fixup!`, `squash!`, `amend!`.
|
|
CC3 | contrib-allowed-authors | >= 0.18.0 | Enforce that only authors listed in the `AUTHORS` file are allowed to commit.
|
|
|
|
## CT1: contrib-title-conventional-commits ##
|
|
|
|
ID | Name | gitlint version | Description
|
|
------|---------------------------------------|--------------------|-------------------------------------------
|
|
CT1 | contrib-title-conventional-commits | >= 0.12.0 | Enforces [Conventional Commits](https://www.conventionalcommits.org/) commit message style on the title.
|
|
|
|
### Options ###
|
|
|
|
Name | gitlint version | Default | Description
|
|
---------------|--------------------|--------------|----------------------------------
|
|
types | >= 0.12.0 | `fix,feat,chore,docs,style,refactor,perf,test,revert,ci,build` | Comma separated list of allowed commit types.
|
|
|
|
|
|
## CC1: contrib-body-requires-signed-off-by ##
|
|
|
|
ID | Name | gitlint version | Description
|
|
------|---------------------------------------|--------------------|-------------------------------------------
|
|
CC1 | contrib-body-requires-signed-off-by | >= 0.12.0 | Commit body must contain a `Signed-off-by` line. This means, a line that starts with the `Signed-off-by` keyword.
|
|
|
|
|
|
## CC2: contrib-disallow-cleanup-commits ##
|
|
|
|
ID | Name | gitlint version | Description
|
|
------|----------------------------------|--------------------|-------------------------------------------
|
|
CC2 | contrib-disallow-cleanup-commits | >= 0.18.0 | Commit title must not contain `fixup!`, `squash!` or `amend!`. This means `git commit --fixup` and `git commit --squash` commits are not allowed.
|
|
|
|
## CC3: contrib-allowed-authors ##
|
|
|
|
ID | Name | gitlint version | Description
|
|
------|----------------------------------|--------------------|-------------------------------------------
|
|
CC3 | contrib-allowed-authors | >= 0.18.0 | The commit author must be listed in an `AUTHORS` file to be allowed to commit. Possible file names are also `AUTHORS.txt` and `AUTHORS.md`.
|
|
|
|
## Contributing Contrib rules
|
|
|
|
We'd love for you to contribute new Contrib rules to gitlint or improve existing ones! Please visit the [Contributing](contributing.md) page on how to get started.
|