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.
SKILL.md
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.
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.
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.
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.
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.
For SARIF upload to GitHub code scanning, add github/codeql-action/upload-sarif after the lint step.
After any configuration, baseline, or rule change, run the exact CI lint command
locally or in a validation job. On a nonzero exit, inspect and fix the new
violations, then rerun the same command until it passes; do not regenerate the
baseline merely to hide the failure.
Homebrew or Docker install, run swiftlint directly
Pre-commit hook
Homebrew install + .pre-commit-config.yaml or git hook script
The build tool plugin is preferred for local development because it requires no PATH configuration, pins the SwiftLint version via package resolution, and runs automatically on build.
Running --fix in a build phase. Auto-fixing on every build creates unpredictable source modifications. Run --fix manually.
Using only_rules without understanding the implication. This disables all rules except those listed. Most teams should use disabled_rules + opt_in_rules instead.
Suppressing with // swiftlint:disable all and forgetting to re-enable. This silently disables all linting for the rest of the file.
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.
Excluding too broadly. Excluding Tests/ entirely means test code gets no linting. Use a child config with relaxed rules instead.
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.
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.
Not configuring included paths. Without included, SwiftLint scans the working directory recursively, which may pick up vendored or generated code.
Review Checklist
.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)
Baseline does not grow unintentionally, and CI is green before the next
rule or cleanup batch
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/rule-reference.md — Bundled exhaustive rule index for local lookup; verify current details with swiftlint rules or the official rule directory
