Swiftlint

SwiftLint

SwiftLint enforces Swift style and conventions by linting source files against a configurable rule set. This skill covers setup, configuration, rule selection, suppression, CI integration, and rollout strategy.

SwiftLint is a style enforcement tool, not a style guide. For underlying Swift naming and design conventions, see swift-api-design-guidelines. For architecture patterns, see swift-architecture.

Contents

• Recommended Setup
• Configuration
• Rule Selection Strategy
• Suppressions
• Baselines
• Autocorrect
• CI Integration
• Integration Decision Tree
• Multiple Configurations
• Common Mistakes
• Review Checklist
• References

Recommended Setup

Default: build tool plugin via `SimplyDanny/SwiftLintPlugins`.

Add the plugin package to Package.swift or via Xcode's package dependencies:

// Package.swift
dependencies: [
  .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "<reviewed-version>")
]

For SwiftPM targets, apply the plugin:

.target(
    name: "MyApp",
    plugins: [.plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")]
)

For Xcode projects without a Package.swift, add the package dependency in the project settings, then enable the plugin under the target's Build Phases or the package's plugin trust dialog.

The build tool plugin runs SwiftLint automatically on every build. No run script required.

First build: Xcode prompts to trust the plugin. Select "Trust & Enable All" for the SwiftLintPlugins package.

For alternatives (run scripts, command plugin, Homebrew CLI), see references/plugins-run-scripts-and-integrations.md.

Configuration

Create .swiftlint.yml at the project root. SwiftLint loads the main configuration from the invocation or plugin working directory, then can merge the nearest nested .swiftlint.yml for each file when configs are discovered automatically. Passing --config overrides automatic discovery and disables nested-config lookup.

# .swiftlint.yml — conservative starter config
disabled_rules:
  - trailing_whitespace
  - todo

opt_in_rules:
  - empty_count
  - closure_spacing
  - force_unwrapping
  - sorted_imports
  - vertical_whitespace_opening_braces
  - private_swiftui_state
  - unhandled_throwing_task
  - accessibility_label_for_image

included:
  - Sources
  - Tests

excluded:
  - .build
  - DerivedData
  - "**/.build"
  - "**/Generated"

line_length:
  warning: 140
  error: 200

type_body_length:
  warning: 300
  error: 500

file_length:
  warning: 500
  error: 1000

Key configuration options:

For full configuration details including severity tuning, environment-variable interpolation, and nested/remote configs, see references/adoption-and-configuration.md.

Rule Selection Strategy

SwiftLint ships with three rule categories:

1. Default rules — enabled automatically, cover widely accepted conventions
2. Opt-in rules — disabled by default, enable selectively via opt_in_rules
3. Analyzer rules — require compiler logs, enabled via analyzer_rules

Browse the full categorized list at <https://realm.github.io/SwiftLint/rule-directory.html>.

Recommended approach for new projects:

1. Start with defaults. Run swiftlint rules to see which rules are enabled.
2. Disable rules that conflict with your team's established conventions.
3. Add opt-in rules one at a time. Review violations before committing each addition.
4. Do not use only_rules unless you have a specific reason to start from zero.

Recommended approach for existing codebases:

1. Start with the default rule set.
2. Create a baseline (see Baselines) to suppress all existing violations.
3. Run the same strict, baseline-aware command used by CI and fix every new violation.
4. Re-run until green before enabling another rule or starting the next cleanup batch.
5. Burn down baseline violations incrementally without accepting baseline growth.

Do not transcribe or memorize the rule directory. Look up rule identifiers and configuration options at the official rule directory when needed.

Suppressions

Suppress SwiftLint for specific lines when a rule produces a false positive or when the violation is intentional and reviewed.

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

let legacy = try! JSONDecoder().decode(T.self, from: data) // swiftlint:disable:this force_try

// swiftlint:disable:previous large_tuple

Disable for a region:

// swiftlint:disable cyclomatic_complexity
func complexRouter(...) { ... }
// swiftlint:enable cyclomatic_complexity

Disable all rules (use sparingly):

// swiftlint:disable all
// ... generated or legacy code ...
// swiftlint:enable all

Policy:

• Prefer targeted single-rule suppressions over all.
• Always re-enable after the region ends.
• For generated code, prefer excluded paths in .swiftlint.yml over inline suppressions.
• For test targets with different tolerance, use a child configuration (see Multiple Configurations).

For full suppression syntax, see references/rules-suppressions-and-baselines.md.

Baselines

Baselines let you adopt SwiftLint in an existing codebase without fixing every legacy violation first.

Create a baseline:

swiftlint --write-baseline .swiftlint.baseline

This records all current violations. Future runs compare against this baseline and only report new violations.

Use the baseline:

swiftlint --baseline .swiftlint.baseline

In CI, pass --baseline so only new violations fail the build. Burn down the baseline over time by fixing legacy violations and regenerating.

For baseline workflows and rollout strategy, see references/rules-suppressions-and-baselines.md.

Autocorrect

SwiftLint can fix some violations automatically:

swiftlint --fix
# or the legacy alias:
swiftlint --autocorrect

Warnings:

• Never run `--fix` as a pre-compile build phase. Auto-fixes modify source files. If run automatically on every build, this creates an unpredictable edit-build loop and can mask real issues.
• Run --fix manually or in a dedicated CI step, then review the diff.
• Not all rules support autocorrect. Check swiftlint rules — the "Correctable" column shows which rules can auto-fix.
• Always commit or stash before running --fix.

CI Integration

CI is the primary enforcement surface. A CI check ensures no one merges code that increases the violation count.

Recommended CI pattern:

# GitHub Actions example
- name: Lint
  run: |
    brew install swiftlint