/swiftlint

name: swiftlint
description: "Configures and enforces SwiftLint in Swift projects using build tool plugins, run scripts, and CI. Covers .swiftlint.yml configuration, disabled_rules, opt_in_rules, only_rules, analyzer_rules, baselines, autocorrect, swiftlint:disable suppressions, reporter formats (sarif, json, checkstyle), strict and lenient modes, SwiftLintBuildToolPlugin via SimplyDanny/SwiftLintPlugins, swift package plugin swiftlint, Xcode run script phases, CI integration, multiple configuration files, and rollout strategies for existing codebases. Use when setting up SwiftLint, configuring lint rules, suppressing warnings, creating baselines, choosing between build tool plugin and run script, or integrating SwiftLint into CI."

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](#recommended-setup)
• [Configuration](#configuration)
• [Rule Selection Strategy](#rule-selection-strategy)
• [Suppressions](#suppressions)
• [Baselines](#baselines)
• [Autocorrect](#autocorrect)
• [CI Integration](#ci-integration)
• [Integration Decision Tree](#integration-decision-tree)
• [Multiple Configurations](#multiple-configurations)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#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](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:

| Key | Purpose | |-----|---------| | `disabled_rules` | Turn off default-enabled rules | | `opt_in_rules` | Turn on rules not enabled by default | | `only_rules` | Use _only_ the listed rules (mutually exclusive with `disabled_rules`/`opt_in_rules`) | | `analyzer_rules` | Rules requiring compiler logs (run via `swiftlint analyze`) | | `baseline` | Path to an existing baseline file used to suppress known violations | | `write_baseline` | Path where SwiftLint should write a new baseline file | | `included` | Paths to lint (default: current directory) | | `excluded` | Paths to skip | | `strict` | Elevate all warnings to errors | | `lenient` | Downgrade all errors to warnings | | `allow_zero_lintable_files` | Suppress the error when no Swift files are found | | `reporter` | Output format: `xcode` (default), `json`, `checkstyle`, `sarif`, `csv`, `emoji`, etc. |

For full configuration details including severity tuning, environment-variable interpolation, and nested/remote configs, see [references/adoption-and-configuration.md](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](#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. Loo