skip to content

In SwiftLint's .swiftlint.yml, how do opt_in_rules, disabled_rules and only_rules differ, and which of them can you combine?

level: juniorimportance: must knowfreq 70%

answer

  1. default set, plus or minus
  2. some rules stay off until listed
  3. an allow-list replaces the defaults
  4. only_rules refuses the other two keys
  5. analyzer_rules is a separate list

basics

~20 s

SwiftLint starts from its default rule set: disabled_rules removes default rules, opt_in_rules adds rules that are off by default, and only_rules replaces the whole set with an explicit list, so it cannot be combined with the other two.

solid answer

~40 s

Every built-in SwiftLint rule is either on by default or opt-in. `disabled_rules` subtracts default rules, `opt_in_rules` adds opt-in ones such as `force_unwrapping` or `empty_count`, and the two work together. `only_rules` is an allow-list: exactly the listed rules run and nothing else, so SwiftLint rejects a file that also sets `disabled_rules` or `opt_in_rules`. A fourth list, `analyzer_rules`, holds the rules only `swiftlint analyze` runs. Two traps: tuning a rule's options under its identifier does not enable an opt-in rule, and with `only_rules` your regex rules run only if the literal `custom_rules` is in the list. `swiftlint rules --enabled` shows what your configuration actually turns on.

code

yaml · 10 lines
yaml
# .swiftlint.yml - defaults with adjustments
disabled_rules:
  - todo
opt_in_rules:
  - force_unwrapping
  - empty_count
analyzer_rules:
  - unused_import
force_unwrapping:
  severity: error

go deeper

for a junior

Recall the three keys: disabled_rules removes default rules, opt_in_rules adds off-by-default ones, only_rules is a complete allow-list. Name one opt-in rule such as force_unwrapping.

for a middle

Explain why only_rules cannot sit beside the other two, why a rule's options block does not enable it, and that custom_rules must be listed in only_rules.

for a senior

Show you check the effective set with swiftlint rules --enabled, and know a rejected file found automatically falls back to the defaults instead of failing the build.

for a principal

Weigh only_rules' stability across upgrades against defaults-plus-adjustments, which picks up new default rules as SwiftLint ships them.

## The default set and the opt-in rules SwiftLint ships more than 200 built-in rules, and each one is either **enabled by default** or **opt-in**. A default rule such as `line_length`, `todo`, `trailing_whitespace` or `force_cast` runs as soon as SwiftLint runs, even with no configuration file at all. An opt-in rule runs only when your `.swiftlint.yml` asks for it. The README gives the reasons a rule is made opt-in: - it can produce many false positives (`empty_count` is the README's example); - it is too slow to run on every lint; - it is not general consensus or only useful in some codebases (`force_unwrapping` is the example). A third family, the **analyzer rules** (`unused_import`, `unused_declaration`, `explicit_self`, `capture_variable`, `typesafe_array_init`), needs a compiler log and runs only under `swiftlint analyze`. They are all opt-in. ## The selection keys side by side | Key | Starts from | Effect | Can be combined with | |---|---|---|---| | `disabled_rules` | the default set | removes the listed default rules | `opt_in_rules` | | `opt_in_rules` | the default set | adds the listed opt-in rules | `disabled_rules` | | `only_rules` | nothing | runs exactly the listed rules | neither of the above | | `analyzer_rules` | its own list | rules that only `swiftlint analyze` runs | either mode | For a seven-year-old insurance-claims app, a typical first file keeps the defaults, drops one rule the team does not want and adds two opt-in rules: ```yaml disabled_rules: - todo opt_in_rules: - force_unwrapping - empty_count analyzer_rules: - unused_import ``` Two keywords and one special identifier matter here: - `all` in `opt_in_rules` enables every opt-in lint rule except those named in `disabled_rules`; it does not pull in analyzer rules. - `all` in `analyzer_rules` enables every analyzer rule. - With `only_rules`, regex rules from `custom_rules` run only if the literal string `custom_rules` is one of the listed entries. ## What happens when only_rules meets the other keys `only_rules` means "this list and nothing else", so adding or removing rules relative to a default set makes no sense beside it. SwiftLint reports that `disabled_rules` or `opt_in_rules` cannot be used in combination with `only_rules`, and what happens next depends on how the file was found: 1. When SwiftLint picked up `.swiftlint.yml` on its own, it prints that error followed by "Falling back to default configuration" and lints with the defaults. Your whole file is ignored, which is easy to miss in a long build log. 2. When you passed the file explicitly with `--config`, SwiftLint prints the error and stops with "Could not read configuration". ## Configuring a rule is not enabling it A rule's options sit under its identifier at the top level of the file: ```yaml force_unwrapping: severity: error ``` For an opt-in rule this only tunes it. If `force_unwrapping` is not also in `opt_in_rules`, SwiftLint warns "Found a configuration for 'force_unwrapping' rule, but it is not enabled in 'opt_in_rules'." and the rule stays off. The same family of warnings covers a rule configured but removed by `disabled_rules`, or configured but missing from `only_rules`. Severity follows the same pattern for any enabled rule: `force_cast: warning` lowers a default error rule to a warning, `line_length: 110` sets only its warning threshold, and an array such as `type_body_length: [300, 400]` sets the warning and error thresholds together. Listing an identifier twice produces "'empty_count' is listed 2 times in the configuration." Listing an analyzer rule under `opt_in_rules` earns a warning that it belongs in `analyzer_rules`, because only `swiftlint analyze` runs it. ## Checking what is actually enabled Read the effective result rather than the file: - `swiftlint rules` prints a table with each rule's identifier and columns for opt-in, correctable, "enabled in your config", kind and analyzer. - `swiftlint rules --enabled` or `--disabled` filters that table to one side. - On the command line, `--only-rule <id>` (repeatable) runs just those rules and ignores `only_rules`, `opt_in_rules` and `disabled_rules`; `swiftlint lint --enable-all-rules` runs every rule, opt-in and disabled ones included. Both are for one-off investigation, not for the build. Choose `disabled_rules` plus `opt_in_rules` when you want SwiftLint's defaults with adjustments, and `only_rules` when the team wants a short, fully explicit list that does not grow when a new SwiftLint release adds default rules. Either way, commit the file at the repository root so every developer, the build and CI read the same selection.

  • Why might a team prefer only_rules even though it takes more typing?
    With `only_rules` the enabled set is exactly what the file lists, so a SwiftLint upgrade that adds new default rules does not suddenly add violations to the build. The cost is that useful new rules never arrive unless someone adds them, and every regex rule needs the literal `custom_rules` entry in the list.
  • You set severity: error under force_unwrapping, yet no force unwrap is reported. What is wrong?
    `force_unwrapping` is opt-in, and a configuration block under its identifier only tunes it. SwiftLint warns that it found a configuration for the rule but it is not enabled in `opt_in_rules`. Add `force_unwrapping` to `opt_in_rules` and the severity applies.

  • Putting force_unwrapping options in the file enables the rule.
  • only_rules adds rules on top of the default set.
  • only_rules and opt_in_rules can be mixed freely in one file.
  • opt_in_rules: [all] also turns on every analyzer rule.
  • Analyzer rules run during a normal swiftlint lint.
  • A broken .swiftlint.yml always stops SwiftLint with an error.