Silencing Issues

Qlty supports a universal inline code comment syntax to silence issues generated during analysis. This feature is supported both locally in Qlty CLI and remotely in Qlty Cloud.

Introducing the qlty-ignore Directive

The qlty-ignore comment directive can be added to a comment on or before the an offending line of code to ignore any issues generated during analysis. Each directive line can contain one or more rule specifiers that will either ignore or unignore a rule. Each rule specifier can either apply to the next line, or be toggled on until it is turned off by a following directive. More details on the rule specifier syntax are provided later.

Basic Usage

To silence an issue generated in the following variable declaration, you can use the following comment syntax:

1
// qlty-ignore: eslint:camelcase
2
var my_variable = 42; // This line will no longer generate an issue

This will ignore one ESLint rule (camelcase), but we did not silence the no-var rule. To silence both, we have a few different options:

Multiple Rules in a Single Directive

The ignore directive supports a comma or space delimited set of rules to ignore which we can use to specify multiple:

1
// qlty-ignore: eslint:camelcase, eslint:no-var
2
var my_variable = 42;

Adjacent Directive Lines are Additive

We can provide multiple adjacent qlty-ignore directive lines each specifying a separate rule to ignore:

1
/**
2
 * qlty-ignore: eslint:camelcase
3
 * qlty-ignore: eslint:no-var
4
 */
5
var my_variable = 42;

Rules will only apply to the next matching line of non-commented code (whitespace lines are ignored).

Ignoring All Rules From a Tool

Finally, we can ignore all eslint rules by just providing the tool name as the rule specifier:

1
// qlty-ignore: eslint
2
var my_variable = 42;

Same-Line comments

If the language supports it, you can also place the ignore directive on the same line as the offending code:

1
var my_variable = 42; // qlty-ignore: eslint:camelcase

Long-Form Directive Syntax

In addition to the initial basic comment syntax, the qlty-ignore directive line can also be adjusted to support the addition of a helpful documentation comment to the ignore for developers to understand why the ignore was added. To add a comment to the ignore directive, use the following syntax:

1
// qlty-ignore(eslint:camelcase): public API cannot be renamed.
2
export const my_variable = 42;

Indented Blocks and Regions

Silencing an Indented Block (Implicit Region)

By default, a rule in a directive will apply to the next line and all subsequently indented lines of code. This indentation can be the continuation of a single statement or the grouping of an entire language construct like an if block, for loop, or even function declaration. In other words, for most formatted languages, applying the directive to a statement will silence all issues up until the end of the block. This is known as an “implicit region”.

Consider the following if statement:

1
# qlty-ignore: pylint:line-too-long
2
if some_very_long_condition_that_is_true:
3
    print("...Very long string...") # issue is also ignored on this line

Because the directive is applied to the if statement, the issue is also ignored on the subsequent line as part of the matching block. In order to opt out of this indentation behavior, you can use the > prefix to enforce the rule to only apply to the next line:

1
# qlty-ignore: >pylint:line-too-long
2
if some_very_long_condition_that_is_true:
3
    print("...Very long string...") # issue is not ignored on this line

Silencing a Region or an Entire File

To silence a rule for an entire file or a region of code, you can use the + prefix to begin a silenced region and the - prefix to end it. This can be useful for silencing rules for an entire file or for a large block of code. For example:

1
# qlty-ignore: +pylint:unused-argument
2
3
def my_function(unused_arg):
4
    pass
5
6
def other_function(unused_arg):
7
    pass
8
9
# qlty-ignore: -pylint:unused-argument
10
11
# issue is not silenced on this line
12
def my_function(unused_arg):
13
    pass

If you want to silence an entire file, simply place a qlty-ignore: +rule directive at the top of a file with no matching -rule directive:

1
// qlty-ignore: +clippy
2
3
fn main() {
4
    let x = 42;
5
}
6
7
// ... remaining file contents ...

Unsilencing a Line in a Silenced Region

If your language supports same line comments, you can unsilence a rule for a single line within a silenced region by using the -rule in a same line qlty-ignore directive comment:

1
// qlty-ignore(clippy): silence _almost_ all lint issues in this function
2
fn main() {
3
    let x = 42; // qlty-ignore(-clippy): except we don't silence this one
4
    let y = 43; // this issue is silenced again
5
}

Rule Specifier Syntax Details

A rule specifier is made up of an optional prefix followed by a tool name and optional rule name qualifier (separated by : or /) as defined in the following grammar:

1
rule-specifier = [prefix] tool-name [(":" / "/") rule-name]
2
prefix = "+" / "-" / ">"
3
tool-name = [a-zA-Z0-9_-]+
4
rule-name = [a-zA-Z0-9_-]+

Prefixes

The following prefixes can be used to control the behavior of the rule specifier:

• +: Begins a region in which the rule is ignored until the matching -rule prefix or the end of the file, whichever comes first.
• -: Ends a region in which the rule is ignored. This can also be applied to same line comments to temporarily unsilence an issue for a single line within a silenced region.
• >: Apply the rule to the next line only, ignoring all indentation matching that would otherwise occur.

When no prefix is used, the next non-comment / non-empty line and all subsequent indented lines will be ignored.