/swiftlint

Rules, Suppressions, and Baselines

Guidance on SwiftLint rule categories, inline suppression syntax, baseline workflows, and false-positive handling.

Contents

• Rule Categories
• Browsing Rules
• Suppression Syntax
• Suppression Policy
• Baselines
• False Positives
• Generated Code and Test Targets

Rule Categories

SwiftLint rules fall into three categories:

Default rules

Enabled automatically. These cover widely agreed-upon conventions (e.g., line_length, force_cast, trailing_semicolon). Disable specific ones via disabled_rules in .swiftlint.yml.

Opt-in rules

Disabled by default because they are more opinionated or may not suit every project. Enable selectively via opt_in_rules:

opt_in_rules:
  - empty_count
  - closure_spacing
  - force_unwrapping
  - sorted_imports
  - contains_over_filter_count
  - first_where
  - last_where
  - modifier_order
  - vertical_whitespace_opening_braces
  - explicit_init
  - joined_default_parameter
  - redundant_nil_coalescing
  - private_swiftui_state
  - unhandled_throwing_task
  - accessibility_label_for_image
  - accessibility_trait_for_button

Analyzer rules

Require the Swift compiler's AST information. Must be run via swiftlint analyze with compiler logs. See the custom rules and analyze reference linked from SKILL.md.

analyzer_rules:
  - unused_import
  - unused_declaration

Browsing Rules

List all rules and their status:

swiftlint rules                    # all rules with enabled/disabled/correctable status
swiftlint rules --enabled          # only currently enabled rules
swiftlint rules --disabled         # only currently disabled rules
swiftlint rules <rule_identifier>  # detailed info for one rule

The official rule directory provides descriptions, configuration options, and examples for every rule.

Do not memorize or transcribe the rule directory. Look up specific rules when needed.

Commonly Encountered Rules Quick Reference

An agent writing or reviewing Swift code should understand what these frequently triggered rules enforce. Each rule can be configured in .swiftlint.yml using the rule identifier as a key.

Default rules (enabled automatically)

High-value opt-in rules

Analyzer rules (require compiler logs)

Per-rule configuration pattern

Every rule that accepts configuration uses its identifier as the YAML key:

# Threshold-based rules use warning/error:
line_length:
  warning: 140
  error: 200

# Boolean option rules:
trailing_comma:
  mandatory_comma: true

# Rules with excluded identifiers:
identifier_name:
  excluded:
    - id
    - x
    - y

# Rules with a single severity override:
force_cast: error    # shorthand for severity: error

# Deployment target rule:
deployment_target:
  iOS_deployment_target: "16.0"

Run swiftlint rules <rule_identifier> to see all available configuration keys for any rule.

Suppression Syntax

Single-line suppressions

// swiftlint:disable:next force_cast
let view = object as! UIView

let value = dict["key"]! // swiftlint:disable:this force_unwrapping

// swiftlint:disable:previous large_tuple

• :next — suppresses on the next line
• :this — suppresses on the same line
• :previous — suppresses on the previous line

Region suppressions

// swiftlint:disable cyclomatic_complexity function_body_length
func complexLegacyFunction() {
    // ... long function ...
}
// swiftlint:enable cyclomatic_complexity function_body_length

Multiple rules can be listed in one directive, separated by spaces.

Disable all rules

// swiftlint:disable all
// ... entire block is unlinted ...
// swiftlint:enable all

If you forget // swiftlint:enable all, the rest of the file is unlinted. This is a common mistake.

Suppression Policy

• Target specific rules. Never use // swiftlint:disable all unless the block is generated code that cannot be excluded via config.
• Add a reason. Follow the suppression with a brief comment explaining why:

// swiftlint:disable:next force_cast — guaranteed by Interface Builder outlet type
let cell = tableView.dequeueReusableCell(...) as! CustomCell

• Re-enable after regions. Always pair disable with enable.
• Prefer config-level exclusion for entire files or directories of generated code.
• Review suppressions in code review. Inline suppressions should be as scrutinized as the code they protect.
• Treat suppressions as tech debt. Track and reduce them over time.

Baselines

Baselines record all existing violations so only new violations are reported.

Creating a baseline

swiftlint --write-baseline .swiftlint.baseline

This creates a JSON file listing every current violation by file, line, and rule. Commit this file to the repository.

Using a baseline

swiftlint --baseline .swiftlint.baseline

Violations matching the baseline are suppressed. New violations (new files, new lines, new rules) are reported normally.

Updating a baseline

After fixing violations, regenerate:

swiftlint --write-baseline .swiftlint.baseline

The new baseline will be smaller. Commit the update.

Baseline in CI

swiftlint --strict --baseline .swiftlint.baseline --reporter github-actions-logging

This fails the build only on new violations not present in the baseline.

Baseline vs suppressions

False Positives

When SwiftLint flags code incorrectly:

1. Check if it's a real false positive by reading the rule description in the rule directory.
2. Check your config — threshold tuning may resolve it (e.g., raising line_length for a file with long URLs).
3. Suppress with a reason if it's genuinely incorrect.
4. File an issue at realm/SwiftLint if the false positive is reproducible and affects others.

Generated Code and Test Targets

Generated code

Exclude generated code directories in .swiftlint.yml:

excluded:
  - "**/Generated"
  - "**/Derived"
  - "**/*.generated.swift"

This is preferable to inline // swiftlint:disable all markers because it keeps generated files completely out of the lint pass.

Test targets

Tests legitimately use patterns that production code should avoid (force unwraps, long functions, etc.). Use a child .swiftlint.yml in the test directory:

# Tests/.swiftlint.yml
disabled_rules:
  - force_unwrapping
  - force_try
  - force_cast
  - function_body_length
  - type_body_length
  - file_length

This is better than excluding tests entirely, because tests still benefit from formatting rules, naming conventions, and other applicable checks.