4.7 KiB
4.7 KiB
Using Contrib Rules
Introduced in gitlint v0.12.0
Contrib rules are community-contributed 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 rules.
To enable certain contrib rules, you can use the --contrib flag.
$ 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:
[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.
Available Contrib Rules
| ID | Name | gitlint version | Description |
|---|---|---|---|
| CT1 | contrib-title-conventional-commits | >= 0.12.0 | Enforces Conventional Commits 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 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 page on how to get started.