## Linter Configuration

Configuration related to the behavior of the linter. These keys are set in the `[lint]` section.

##### `lint_on_build`

* Type: boolean
* Default: `true`
* Environment: `FOUNDRY_LINT_ON_BUILD`

Whether to run linting during `forge build`. Set to `false` to disable automatic linting during builds.

##### `severity`

* Type: array of strings
* Default: `[]`
* Environment: `FOUNDRY_LINT_SEVERITY`

Specifies which lints to run based on severity. Valid values are:

* `high`
* `medium` (or `med`)
* `low`
* `info`
* `gas`
* `code-size` (or `codesize`, `size`)

An empty list means no severity filter is applied, so all severity buckets are
enabled. To run only warning-level lints, set this explicitly to
`["high", "medium", "low"]`.

##### `exclude_lints`

* Type: array of strings
* Default: `[]`
* Environment: `FOUNDRY_LINT_EXCLUDE_LINTS`

List of lint IDs to exclude from checking (e.g., `"mixed-case-function"`).

##### `ignore`

* Type: array of strings (patterns)
* Default: `[]`
* Environment: `FOUNDRY_LINT_IGNORE`

List of files or patterns to ignore when running the linter. This is a comma-separated list of glob patterns.

##### `mixed_case_exceptions`

* Type: array of strings
* Default: `["ERC", "URI"]`
* Environment: `FOUNDRY_LINT_MIXED_CASE_EXCEPTIONS`

Configurable patterns that should be excluded when performing `mixedCase` lint checks. Defaults to `["ERC", "URI"]` to allow common names like `rescueERC20`, `ERC721TokenReceiver`, or `tokenURI`.

## Inline Configuration

The linter also offers the ability to disable lints for specific sections of code using inline comment directives.
This is useful when you need to suppress false positives or have valid reasons for code that would otherwise trigger a lint warning.

To disable lints using inline config, your comment must follow this format:

```
/// forge-lint: <directive>(<lint-ids>)
```

Where:

* `<directive>` is one of the directives from the table below
* `<lint-ids>` is a comma-separated list of lint identifiers, or `all` to disable all lints

### Supported Inline Directives

| Directive                       | Description                                                                        | Scope                              |
| ------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
| `disable-next-item`             | Disables lints for the next code item (contract, function, variable, struct, etc.) | Next item regardless of line count |
| `disable-line`                  | Disables lints for the current line                                                | Current line only                  |
| `disable-next-line`             | Disables lints for the next line                                                   | Next line only                     |
| `disable-start` / `disable-end` | Disables lints for all code between the start and end comments                     | Block of code between directives   |

### Best Practices

1. **Be Specific**: Always specify which lint(s) you're disabling rather than using `all`.
2. **Add Comments**: Explain why you're disabling the lint to help future maintainers.
3. **Minimize Scope**: Use the most targeted directive possible (e.g., `disable-line` instead of `disable-start/end`).

### Disabling Linter On Build

By default, the linter runs automatically when you build your project with `forge build`.

To skip linting for a single invocation, pass `--no-lint` (alias `--skip-lint`):

```bash
forge build --no-lint
```

To disable persistently, in your `foundry.toml` set:

```toml
[lint]
lint_on_build = false
```

It is however recommended to keep linting enabled during development to catch issues early.
We are continuously improving the linter and you may be missing out on valuable feedback by disabling it.

It is better to configure your `foundry.toml` to only run specific severities by setting the [`severity`](#severity) key, exclude
certain lints with [`exclude_lints`](#exclude_lints), or ignore certain files with [`ignore`](#ignore).