> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  We use the C style `// comment` format in many of our examples, but rest assured that the ignore
  directive can be used in any comment block using any language supported comment syntax.
</Note>

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:

```js lines theme={"system"}
// qlty-ignore: eslint:camelcase
var my_variable = 42; // This line will no longer generate an issue
```

<Tip>
  When specifying an individual rule, make sure to provide the fully qualified rule name as listed
  by Qlty results. In the above example, we ignore the `camelcase` rule from the `eslint` tool as
  `eslint:camelcase`.
</Tip>

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:

```js lines theme={"system"}
// qlty-ignore: eslint:camelcase, eslint:no-var
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:

```js lines theme={"system"}
/**
 * qlty-ignore: eslint:camelcase
 * qlty-ignore: eslint:no-var
 */
var my_variable = 42;
```

<Note>
  We used the block style `/* */` comment syntax here for illustration purposes. Any set of
  adjacent comment lines would work.
</Note>

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:

```js lines theme={"system"}
// qlty-ignore: eslint
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:

```js lines theme={"system"}
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:

```js lines theme={"system"}
// qlty-ignore(eslint:camelcase): public API cannot be renamed.
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:

```python lines theme={"system"}
# qlty-ignore: pylint:line-too-long
if some_very_long_condition_that_is_true:
    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:

```python lines theme={"system"}
# qlty-ignore: >pylint:line-too-long
if some_very_long_condition_that_is_true:
    print("...Very long string...") # issue is not ignored on this line
```

<Tip>
  Use the `>` rule specifier prefix to silence a rule on the next line only instead of the rest of
  the indented block.
</Tip>

### 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:

```python lines theme={"system"}
# qlty-ignore: +pylint:unused-argument

def my_function(unused_arg):
    pass

def other_function(unused_arg):
    pass

# qlty-ignore: -pylint:unused-argument

# issue is not silenced on this line
def my_function(unused_arg):
    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:

```rust lines theme={"system"}
// qlty-ignore: +clippy

fn main() {
    let x = 42;
}

// ... 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:

```rust lines theme={"system"}
// qlty-ignore(clippy): silence _almost_ all lint issues in this function
fn main() {
    let x = 42; // qlty-ignore(-clippy): except we don't silence this one
    let y = 43; // this issue is silenced again
}
```

<Note>
  This mechanism can be applied to either implicit (indented blocks) or explicit regions defined
  by `+rule` ... `-rule` pairs.
</Note>

## 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:

```abnf lines theme={"system"}
rule-specifier = [prefix] tool-name [(":" / "/") rule-name]
prefix = "+" / "-" / ">"
tool-name = [a-zA-Z0-9_-]+
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.