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

SimplyDanny/SwiftLintPlugins

Package.swift

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

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

Package.swift

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

• trailing_whitespace
• todo

• empty_count
• closure_spacing
• force_unwrapping
• sorted_imports
• vertical_whitespace_opening_braces
• private_swiftui_state
• unhandled_throwing_task
• accessibility_label_for_image

• Sources
• Tests

• .build
• DerivedData
• "**/.build"
• "**/Generated"

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).

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

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.

1. Start with the default rule set.
2. Create a baseline (see Baselines) to suppress all existing violations.
3. Enforce zero new violations in CI.
4. Burn down baseline violations incrementally.

// 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

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

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

• 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).

• name: Lint run: | brew install swiftlint swiftlint --strict --reporter sarif > swiftlint.sarif

Key CI options:

| Flag | Effect |
|------|--------|
| `--strict` | Exits non-zero on warnings (not just errors) |
| `--reporter sarif` | GitHub Advanced Security compatible output |
| `--reporter json` | Machine-readable output |
| `--reporter checkstyle` | Jenkins/SonarQube compatible |
| `--baseline .swiftlint.baseline` | Only fail on new violations |

For SARIF upload to GitHub code scanning, add `github/codeql-action/upload-sarif` after the lint step.

For full CI recipes and reporter details, see [references/plugins-run-scripts-and-integrations.md](references/plugins-run-scripts-and-integrations.md).

.swiftlint.yml

• Relaxed test config: place a

  .swiftlint.yml

  in

  Tests/

  that disables

  force_unwrapping

  and raises

  file_length

• Strict module config: place a stricter

  .swiftlint.yml

  in a shared module directory
• Remote config: use

  parent_config

  with an HTTPS URL to pull a shared team config (caching supported)

undefined

• force_unwrapping
• force_try

You can also pass multiple configs on the CLI:

```sh
swiftlint --config .swiftlint.yml --config .swiftlint-extra.yml

1. Running

   --fix

   in a build phase. Auto-fixing on every build creates unpredictable source modifications. Run

   --fix

   manually.
2. Using

   only_rules

   without understanding the implication. This disables all rules except those listed. Most teams should use

   disabled_rules

   +

   opt_in_rules

   instead.
3. Suppressing with

   // swiftlint:disable all

   and forgetting to re-enable. This silently disables all linting for the rest of the file.
4. Not pinning the SwiftLint version. Different versions have different default rules. Use the build tool plugin (version pinned via SPM) or pin in your

   Brewfile

   / CI config.
5. Excluding too broadly. Excluding

   Tests/

   entirely means test code gets no linting. Use a child config with relaxed rules instead.
6. Ignoring the toolchain mismatch. SwiftLint must be built with (or compatible with) the same Swift toolchain used to compile your project. Mismatches cause parsing errors. See references/plugins-run-scripts-and-integrations.md for multi-toolchain guidance.
7. Adopting too many opt-in rules at once in a large codebase. This creates an overwhelming number of violations. Add rules incrementally and use baselines.
8. Not configuring

   included

   paths. Without

   included

   , SwiftLint scans the working directory recursively, which may pick up vendored or generated code.

• .swiftlint.yml

  exists at the project root with explicit

  included

  /

  excluded

  paths
• SwiftLint version is pinned (via SPM plugin resolution, Brewfile, or CI config)
• Build tool plugin is enabled for each target that should be linted
• CI runs

  swiftlint --strict

  (or with

  --baseline

  for incremental adoption)
• No

  --fix

  /

  --autocorrect

  in build phases
• Inline suppressions target specific rules, not

  all

• Inline suppressions include a comment explaining why
• Test targets have appropriate config (relaxed rules via child config, not excluded entirely)
• Autocorrect changes are reviewed in a separate commit
• New opt-in rules are added one at a time with team consensus

• references/adoption-and-configuration.md — Installation paths,

  .swiftlint.yml

  deep dive, severity tuning, environment variables, nested/remote configs, rollout strategy
• references/plugins-run-scripts-and-integrations.md — Build tool plugin, command plugin, run scripts, CI recipes, multi-toolchain guidance, VS Code, Fastlane, Docker, pre-commit
• references/rules-suppressions-and-baselines.md — Default vs opt-in vs analyzer rules, suppression syntax, baseline workflows, false-positive handling
• references/rule-reference.md — Bundled exhaustive rule index for local lookup; verify current details with

  swiftlint rules

  or the official rule directory
• references/custom-rules-and-analyze.md — Regex custom rules, Swift custom rules (brief),

  swiftlint analyze

  , compiler-log workflow
• SwiftLint documentation — Official docs
• SwiftLint rule directory — Full categorized rule list
• SimplyDanny/SwiftLintPlugins — Recommended plugin package