The .gitlint file¶

You can modify gitlint's behavior by adding a .gitlint file to your git repository.

Generate a default .gitlint config file by running:

gitlint generate-config

You can also use a different config file like so:

gitlint --config myconfigfile.ini

Example `.gitlint`¶

.gitlint

### GENERAL CONFIG  ### (1)
[general]
# Ignore rules, reference them by id or name (comma-separated)
ignore=title-trailing-punctuation, T3

# verbosity should be a value between 1 and 3
verbosity = 2

# By default gitlint will ignore certain commits (21)
ignore-merge-commits=true
ignore-revert-commits=true
ignore-fixup-commits=true
ignore-fixup-amend-commits=true
ignore-squash-commits=true

# Ignore any data sent to gitlint via stdin
ignore-stdin=true

# Fetch additional meta-data from the local repository when manually passing a
# commit message to gitlint via stdin or --commit-msg. Disabled by default.
staged=true

# Hard fail when the target commit range is empty. 
fail-without-commits=true # (2)

# Whether to use Python `search` instead of `match` semantics in rules (3)
regex-style-search=true

# Enable community contributed rules
contrib=contrib-title-conventional-commits,CC1 # (4)

# Set the extra-path where gitlint will search for user defined rules # (5)
extra-path=examples/


### RULE CONFIGURATION ### (6)
[title-max-length] 
line-length=80

[title-min-length]
min-length=5

[title-must-not-contain-word]
# Comma-separated list of words that should not occur in
# the commit message title (case-insensitive).
words=wip,foobar

[title-match-regex]
regex=^US[0-9]* # (7)

[body-max-line-length]
line-length=120

[body-min-length]
min-length=5

[body-is-missing]
# Ignore this rule on merge commits (default=true) # (8)
ignore-merge-commits=false

[body-changed-file-mention]
# Files that need to be explicitly mentioned in the body when they change
files=gitlint-core/gitlint/rules.py,README.md # (9)

[body-match-regex]
regex=My-Commit-Tag: foo$ # (10)

[author-valid-email]
# E.g.: Only allow email addresses from foo.com
regex=[^@]+@foo.com # (11)


### NAMED RULES ### (20)
[title-must-not-contain-word:Additional-Words]
words=foo,bar


### CONTRIB RULES ### (12)
[contrib-title-conventional-commits]
types = bugfix,user-story,epic


### USER DEFINED RULES ### (19)
[body-max-line-count]
max-line-count = 5


### IGNORE RULES CONFIGURATION ### (13)
[ignore-by-title]
# Ignore rules for commits of which the title matches a regex
regex=^Release(.*) # (14)
ignore=T1,body-min-length # (15)

[ignore-by-body]
# Ignore rules for commits of which the body has a line that matches a regex
regex=(.*)release(.*) # (16)
ignore=T1,body-min-length

[ignore-body-lines]
# Ignore all lines that start with 'Co-Authored-By'
regex=^Co-Authored-By # (17)

[ignore-by-author-name]
regex=(.*)dependabot(.*) # (18)
ignore=T1,body-min-length

This section of the .gitlint file sets overall gitlint behavior. Details about all available [general] options can be found in General Options.
Gitlint will 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.
Disabled by default, but will be enabled by default in the future. More information.
See Contrib Rules.
See User Defined Rules.
All sections below sets rule specific behavior.
Rules and sections can be referenced by their full name or by id. For example, this rule [title-max-length] could also be referenced as [T1].
```
[T1]
line-length=80
```
Python style regex that the commit-msg title must be matched to. Note that the regex can contradict with other rules if not used correctly (e.g. title-must-not-contain-word).
Merge commits often don't have a body, so by default gitlint will ignore this rule for merge commits to avoid unncessary violations.
This is useful for when developers often erroneously edit certain files or git submodules. By specifying this rule, developers can only change the file when they explicitly reference it in the commit message.
Python style regex that the commit-msg body must match. In this case the commit message body must end in
My-Commit-Tag: foo
Python style regex that the commit author email address should be matched to.
Community Contributed rules are disabled by default. You need to explicitly enable them one-by-one by adding them to the contrib option under [general] section. You can then just configure their options like any other rule.
```
[general]
# Enable contrib rules (comma-separated list)
contrib=contrib-title-conventional-commits

# Configure contrib rule
[contrib-title-conventional-commits]
types = bugfix,user-story,epic
```
You can configure gitlint to ignore specific commits or parts of a commit.
Python style regex. This example matches commit titles that start with "Release".
Which rules to ignore (reference by id or name). Use all to ignore all rules.
Python style regex. This example matches bodies that have a line that contains release.
Python style regex. This example will make gitlint ignores all lines that start with Co-Authored-By.
Python style regex. This example will make gitlint ignore certain rules for commits made by dependabot. You can also ignore the the commit all-together by setting ignore=all:
```
[ignore-by-author-name]
regex=(.*)dependabot(.*) # (18)
ignore=all
```
User-Defined rules can be written in python to tailor gitlint to your specific needs.
Named Rules allow you to specify multiple instances of the same rule by given them an extra name of your choosing after the colon sign :.

In the example below we're configuring another instances of the title-must-not-contain-word rule (the existing one will remain active as well) and naming it Additional-Words.
Gitlint ignores merge, revert, fixup, and squash commits by default.

The .gitlint file¶

Example .gitlint¶

Example `.gitlint`¶