SuperAPI AI Directory

swiftlint

General & other

View repository

Updated 10-16 05:52

About this skill

SwiftLint

Enforce Swift style, formatting, and conventions using SwiftLint. Covers build-tool plugins, .swiftlint.yml configuration, staged rollouts, baselines, and CI integration.

Scope Boundary: SwiftLint is a linting and style enforcement tool. For underlying API naming, conventions, and architectural rules, see swift-api-design-guidelines and swift-code-review.

Contents

  • Recommended Setup (Build Tool Plugin)
  • Configuration (.swiftlint.yml)
  • Rule Selection & Rollout
  • Suppressions & Baselines
  • Autocorrect & CI Pipeline
  • Common Mistakes
  • Review Checklist
  • References

Recommended Setup (Build Tool Plugin)

Prefer the build tool plugin from SimplyDanny/SwiftLintPlugins for Xcode projects and Swift Packages. It avoids global machine installs and runs automatically during target compilation:

// Package.swift
dependencies: [
    .package(url: "https://github.com/SimplyDanny/SwiftLintPlugins", from: "0.58.0")
],
targets: [
    .target(
        name: "MyFeature",
        plugins: [
            .plugin(name: "SwiftLintBuildToolPlugin", package: "SwiftLintPlugins")
        ]
    )
]

Configuration (.swiftlint.yml)

Place .swiftlint.yml in the project root:

included:
  - Sources
  - Tests

excluded:
  - Pods
  - .build
  - DerivedData

opt_in_rules:
  - empty_count
  - missing_docs
  - fatal_error_message

disabled_rules:
  - line_length
  - todo

line_length:
  warning: 120
  error: 160

Rule Selection & Rollout

Adopt rules incrementally in existing codebases:

  1. Start with high-confidence default rules; disable noisy formatting rules initially.
  2. Fix autocorrectable violations with swiftlint --fix.
  3. Introduce stricter opt-in rules team-by-team.

Suppressions & Baselines

Suppress legitimate exceptions in code:

// swiftlint:disable:next force_cast
let cell = tableView.dequeueReusableCell(withIdentifier: "Cell") as! CustomCell

// Entire block suppression
// swiftlint:disable cyclomatic_complexity
func complexAlgorithm() { ... }
// swiftlint:enable cyclomatic_complexity

For legacy codebases, capture existing violations into a baseline to prevent regressions without blocking existing files: swiftlint analyze --compiler-log-path xcodebuild.log.

Autocorrect & CI Pipeline

Run in CI before running unit tests:

# Lint with strict error exit codes
swiftlint --strict --reporter github-actions-logging

# Automatically fix whitespace and mechanical violations locally
swiftlint --fix

Common Mistakes

  • Enabling all opt-in rules at once: Overwhelms teams with thousands of warnings. Enable rules iteratively.
  • Global Homebrew dependency without version pinning: Causes divergent lint errors across different team machines. Use Swift Package plugins or pin tool versions.
  • Not excluding build and dependency directories: Linting Pods/ or .build/ dramatically slows down compilation.
  • Overusing broad inline suppressions: Prefer // swiftlint:disable:next rule_id over disabling rules for entire files.
  • Running autocorrect in CI without automated commit: Autocorrect should run locally pre-commit; CI should verify with --strict.

Review Checklist

  • SwiftLint version pinned across developer environments
  • .swiftlint.yml excludes derived data and third-party dependencies
  • Build tool plugin configured on active app and framework targets
  • Suppressions target specific rules and are scoped narrowly
  • CI pipeline fails on lint errors via --strict

References