Project Config (qlty.toml)

Project configuration stored in a qlty.toml file is used by both Qlty CLI and Qlty Cloud. We strongly recommend that this file is commited into Git version control.

This file uses the TOML format and is located at .qlty/qlty.toml in your repository:

$   your-git-repository/
>   ├─ .qlty/
>   │  ├─ ... other qlty files
>   │  └─ qlty.toml
>   └─ ... rest of your repository files

If you do not have a .qlty/qlty.toml file checked in to your repository, Qlty Cloud will generate a new, temporary configuration file before running the analysis using qlty init.

`qlty.toml` Specification

Each field in the qlty.toml file corresponds to a specific configuration setting. Detailed descriptions of these settings are provided below.

`config_version`

The version of the qlty.toml configuration file format. Currently, all config_versions are 0. We may use this field in the future to introduce breaking changes to the configuration file format.

`sources`

sources are defined at the top-level and specify repositories which contain plugin definitions. By convention, sources are placed at the top of the qlty.toml file.

The default auto-generated configuration file will include a default source conveniently named default. You can add additional sources from other Git repositories and name them as you like.

Below are the accepted properties to define a source:

Name	Description
`repository`	The URL of the git repository
`tag`	The tag to fetch from the repository (conflicts with `branch`)
`branch`	The branch to fetch from the repository (conflicts with `tag`)

Follow the example below to add a new source:

1 [sources.example]
2 repository = "https://github.com/example/example.git"
3 branch = "main"

For each source, you can specify either a tag or a branch, but not both. If you specify both, the tag will be used.

`exclude_patterns`

Qlty is Git-aware and honors .gitignore files. The exclude_patterns setting allows you to specify additional directories and/or files that should be completely excluded from all Qlty activities, both from Qlty Cloud and Qlty CLI. This setting uses glob syntax to match file and directory names.

This setting is useful for excluding files that are not relevant for Qlty, such as generated code, build artifacts, temporary files, or third-party libraries. Below is an example of how to customize the exclude_patterns setting to fit your project:

1 exclude_patterns = [
2   "*.log",
3   "**/*.min.js",
4   "**/node_modules/**",
5   "**/*.spec.js"
6 ]

`test_patterns`

The test_patterns setting allows you to specify directories and/or files that should considered automated tests run at build time rather than runtime application code. Qlty Cloud uses this information in order to provide higher qualtiy analysis results.

This setting uses glob syntax to match file and directory names. Below is an example of how to customize the test_patterns setting to fit your project:

1 test_patterns = [
2   "**/test/**",
3   "**/spec/**",
4   "**/test_*.*",
5   "**/spec_*.*",
6   "**/*_test.*",
7   "**/*_spec.*",
8 ]

`smells`

The smells setting defined at the top-level is used to configure the functioning of the qlty smell CLI command, which is employed by Qlty Cloud to identify code smells in your project. This allows you to customize the detection and management of various code quality smells.

These settings apply for all supported programming languages, and can be customized further for each language using the languages setting.

`smells.mode`

The mode setting determines how Qlty Cloud handles detected code smells. Four modes are available:

Mode	Description
`block`	Code smells may fail the Qlty Gate (post them as pull request comments)
`comment` (default)	Post comments on pull requests but never fail the Qlty Gate
`monitor`	Analyze and report smells on Qlty Cloud but never post them to GitHub
`disabled`	Smell detection will be disabled

`smells.[name].enabled`

The enabled setting allows you to enable or disable the detection of specific code smells. By default, all smells are enabled, but you can selectively disable those that are not relevant to your project.

Below is an example of how to enable or disable specific smells:

1 [smells.boolean_logic]
2 enabled = true
3 
4 [smells.nested_control_flow]
5 enabled = false

`smells.[name].threshold`

The smells.[name].threshold setting allows you to fine-tune the parameters for identifying specific types of code smells. Below is a comprehensive list of all available smell settings and their default thresholds:

Smell Name	Threshold	Default
`boolean_logic`	Maximum number of boolean operators (such as `and` or `or`) in a single expression	5
`nested_control_flow`	Maximum number of nested control flow statements	5
`function_parameters`	Maximum number of function parameters	5
`return_statements`	Maximum number of return statements in a function	6
`file_complexity`	Maximum allowed complexity for a single file	50
`function_complexity`	Maximum function complexity	15

`smells.duplication`

The smells.duplication setting is used to configure the detection of duplicated code (copypasta code).

Below is an explanation of the available parameters:

Setting Name	Description	Default
`threshold`	The minimum number of duplicated lines for a piece of code to be considered a code smell	12
`nodes_threshold`	The minimum number of AST children nodes for a single node to be included in the duplication detection	50

Below is an example of how to configure the smells.duplication setting:

1 [smells.duplication]
2 threshold = 10
3 nodes_threshold = 30

This settings will applly to all programming languages. You can customize the duplication detection settings for specific languages using the language setting.

`language.[name]`

The language.[name] setting allows you to customize various settings on a per-language basis, applicable to both Qlty Cloud and Qlty CLI.

`language.[name].smells`

This setting enables you to configure the detection and management of various code quality smells for a specific programming language. Below is an example of how to customize the detection of code smells for a particular language:

1 [language.rust.smells]
2 duplication.filter_patterns = ["(use_declaration _)"]
3 duplication.nodes_threshold = 40
4 function_parameters.threshold = 6
5 function_complexity.threshold = 20

Alternatively, you can use this equally valid TOML syntax:

1 [language.rust.smells.duplication]
2 filter_patterns = ["(use_declaration _)"]
3 nodes_threshold = 40
4 
5 [language.rust.smells.function_parameters]
6 threshold = 6
7 
8 [language.rust.smells.function_complexity]
9 threshold = 6

`[[plugin]]`

Each [[plugin]] entry must be defined at the top-level of the qlty.toml file, specifying the configuration for a specific plugin. You will need one [[plugin]] entry for each plugin you want to enable in your project.

Below are the accepted properties for defining a [[plugin]] entry:

Name	Description
`name`	The plugin name, e.g., eslint, rubocop, etc
`version`	The plugin version, following the version specification used by the plugin (this may vary across plugins)
`enabled`	Whether to enable or disable the plugin
`extra_packages`	Some plugins, like the stylelint plugin, are usually used in combination with other packages such as `stylelint-config-standard-scss`. This setting allows you to define these additional packages. This is also commonly used by other plugins such as eslint and rubocop
`package_file`	This setting is only relevant to some plugins, like eslint, that heavily depend on external files. It specifies where a certain package file is located. For eslint, you may want to indicate the location of your `package.json`
`skip_upstream`	Whether the plugin should run against the upstream or not. The default is `false`

Follow the example below to customize the execution of a plugin:

1 [[plugin]]
2 name = "stylelint"
3 version = "15.10.3"
4 extra_packages = ["stylelint-config-standard-scss@11.0.0"]

To get started with a new plugin, you can run qlty plugins enable <plugin-name> to automatically add the plugin to your qlty.toml file.

`[[ignore]]`

The [[ignore]] block allows you to declare rules to ignore certain issues in your project, applicable to both Qlty Cloud and Qlty CLI. Each [[ignore]] entry can specify conditions based on plugins, rules, file patterns, and issue levels. If an issue matches all the specified conditions, it will be ignored by Qlty.

Below are the accepted properties for defining an [[ignore]] entry:

Name	Description
`file_patterns`	A list of glob patterns to match files that should be ignored. The default pattern is `*` which matches all files
`plugins`	A list of plugin names. Issues reported by these plugins will be ignored
`rules`	A list of rule names. Issues reported by these rules will be ignored. Rules are plugin specific.
`levels`	A list of issue levels. Issues of these levels will be ignored. The different accepted levels are: `fmt`, `low`, `medium`, `high` or `unspecified`

Below are examples of how to use the [[ignore]] setting:

1 # Ignore the eslint react/prop-types check only in react-app/app/components/ui
2 [[ignore]]
3 plugins = ["eslint"]
4 rules = ["eslint/react/prop-types"]
5 file_patterns = ["react-app/app/components/ui/**"]
6 
7 # Ignore all rubocop issues at `low` level
8 [[ignore]]
9 plugins = ["rubocop"]
10 levels = ["low"]
11 
12 # Ignore all issues in `node_modules` directory
13 [[ignore]]
14 file_patterns = ["**/node_modules/**"]

[[ignore]] blocks are evaluated sequentially, and the first match will be applied.

`[[override]]`

The [[override]] block allows you to modify certain properties of issues detected by Qlty. Each [[override]] entry can specify conditions (matchers) based on plugins, rules, and file patterns to determine which issues the overrides apply to. If an issue matches all the specified conditions, its properties will be overridden by the values specified in the [[override]] entry.

Below are the properties for defining an [[override]] entry, divided into matchers and overrides:

Matchers

Name	Description
`plugins`	A list of plugin names. Issues reported by these plugins will be matched
`rules`	A list of rule names. Issues reported by these rules will be matched. Rules are plugin specific
`file_patterns`	A list of glob patterns to match files whose issues should be matched. The default pattern is `*` which matches all files

Overrides

Name	Description
`level`	The new level for the issues that match the conditions. Possible values are `unspecified`, `fmt`, `low`, `medium`, `high`
`category`	The new category for the issues that match the conditions. Accepted categories are: `bug`, `vulnerability`, `structure`, `duplication`, `security_hotspot`, `performance`, `documentation`, `type_check`, `style`, `anti_pattern` and `accessibility`
`mode`	The new mode for the issues that match the conditions. Possible values are `block`, `comment`, `monitor`, `disabled`

Below are examples of how to use the [[override]] setting:

1 # Override the level of eslint react/prop-types issues in react-app/components/ui/ to "low"
2 [[override]]
3 plugins = ["eslint"]
4 rules = ["eslint/react/prop-types"]
5 file_patterns = ["react-app/components/ui/**"]
6 level = "low"
7 
8 # Override the mode of all rubocop issues to "comment"
9 [[override]]
10 plugins = ["rubocop"]
11 mode = "comment"
12 
13 # Override the category of issues in node_modules directory to "dependency"
14 [[override]]
15 file_patterns = ["**/node_modules/**"]
16 category = "dependency"

[[override]] blocks are evaluated sequentially, and the first match will be applied

Glob Syntax Reference

Following, a table that illustrates the most commonly used glob syntaxes accepted by Qlty:

Example Pattern	Matches
`foo.rb`	`foo.rb` at the top-level of the repository
`*.rb`	all files at the top-level that end with `.rb`
`**/foo.rb`	`foo.rb` anywhere in the repository
`*/.rb`	all files that end with `.rb` anywhere in the repository
`/test/`	All folders named `test` at any level

Full Example

The exact auto generated version of your .qlty/qlty.toml file will vary depending on the languages and frameworks used in your project. Below is a general example of how it may look like for a JavaScript project.

1 config_version = "0"
2 
3 exclude_patterns = ["**/node_modules/**","**/vendor/**"]
4 test_patterns = ["**/test/**", "**/spec/**"]
5 
6 [sources.default]
7 repository = "https://github.com/qltysh/qlty.git"
8 tag = "v0.101.0"
9 
10 [[plugin]]
11 name = "actionlint"
12 
13 [[plugin]]
14 name = "checkov"
15 version = "3.2.49"
16 
17 [[plugin]]
18 name = "markdownlint"
19 version = "0.31.1"
20 
21 [[plugin]]
22 name = "osv-scanner"
23 
24 [[plugin]]
25 name = "prettier"
26 version = "2.8.4"
27 
28 [[plugin]]
29 name = "ripgrep"
30 
31 [[plugin]]
32 name = "shellcheck"
33 version = "0.9.0"
34 
35 [[plugin]]
36 name = "shfmt"
37 
38 [[plugin]]
39 name = "trivy"
40 
41 [[plugin]]
42 name = "trufflehog"
43 
44 [[plugin]]
45 name = "yamllint"

The list of auto-enabled plugins provided by the Qlty CLI is a recommended suggestion. You are encouraged to add or remove plugins as needed.

$	your-git-repository/
>	├─ .qlty/
>	│ ├─ ... other qlty files
>	│ └─ qlty.toml
>	└─ ... rest of your repository files

1	[sources.example]
2	repository = "https://github.com/example/example.git"
3	branch = "main"

1	exclude_patterns = [
2	"*.log",
3	"*/.min.js",
4	"/node_modules/",
5	"*/.spec.js"
6	]

1	test_patterns = [
2	"/test/",
3	"/spec/",
4	"*/test_.*",
5	"*/spec_.*",
6	"*/_test.*",
7	"*/_spec.*",
8	]

1	[smells.boolean_logic]
2	enabled = true
3
4	[smells.nested_control_flow]
5	enabled = false

1	[language.rust.smells]
2	duplication.filter_patterns = ["(use_declaration _)"]
3	duplication.nodes_threshold = 40
4	function_parameters.threshold = 6
5	function_complexity.threshold = 20

1	[language.rust.smells.duplication]
2	filter_patterns = ["(use_declaration _)"]
3	nodes_threshold = 40
4
5	[language.rust.smells.function_parameters]
6	threshold = 6
7
8	[language.rust.smells.function_complexity]
9	threshold = 6

1	[[plugin]]
2	name = "stylelint"
3	version = "15.10.3"
4	extra_packages = ["stylelint-config-standard-scss@11.0.0"]

1	# Ignore the eslint react/prop-types check only in react-app/app/components/ui
2	[[ignore]]
3	plugins = ["eslint"]
4	rules = ["eslint/react/prop-types"]
5	file_patterns = ["react-app/app/components/ui/**"]
6
7	# Ignore all rubocop issues at `low` level
8	[[ignore]]
9	plugins = ["rubocop"]
10	levels = ["low"]
11
12	# Ignore all issues in `node_modules` directory
13	[[ignore]]
14	file_patterns = ["/node_modules/"]

1	# Override the level of eslint react/prop-types issues in react-app/components/ui/ to "low"
2	[[override]]
3	plugins = ["eslint"]
4	rules = ["eslint/react/prop-types"]
5	file_patterns = ["react-app/components/ui/**"]
6	level = "low"
7
8	# Override the mode of all rubocop issues to "comment"
9	[[override]]
10	plugins = ["rubocop"]
11	mode = "comment"
12
13	# Override the category of issues in node_modules directory to "dependency"
14	[[override]]
15	file_patterns = ["/node_modules/"]
16	category = "dependency"

1	config_version = "0"
2
3	exclude_patterns = ["/node_modules/","/vendor/"]
4	test_patterns = ["/test/", "/spec/"]
5
6	[sources.default]
7	repository = "https://github.com/qltysh/qlty.git"
8	tag = "v0.101.0"
9
10	[[plugin]]
11	name = "actionlint"
12
13	[[plugin]]
14	name = "checkov"
15	version = "3.2.49"
16
17	[[plugin]]
18	name = "markdownlint"
19	version = "0.31.1"
20
21	[[plugin]]
22	name = "osv-scanner"
23
24	[[plugin]]
25	name = "prettier"
26	version = "2.8.4"
27
28	[[plugin]]
29	name = "ripgrep"
30
31	[[plugin]]
32	name = "shellcheck"
33	version = "0.9.0"
34
35	[[plugin]]
36	name = "shfmt"
37
38	[[plugin]]
39	name = "trivy"
40
41	[[plugin]]
42	name = "trufflehog"
43
44	[[plugin]]
45	name = "yamllint"

qlty.toml Specification

config_version

sources

exclude_patterns

test_patterns

smells

smells.mode

smells.[name].enabled

smells.[name].threshold

smells.duplication

language.[name]

language.[name].smells

[[plugin]]

[[ignore]]

[[override]]