Swiftlint

SwiftLint

Enforce Swift style and conventions with static analysis. Lint entire projects, autocorrect fixable violations, manage rules, and integrate with Xcode and CI — all from the CLI.

Verify Installation

swiftlint version

If not installed:

brew install swiftlint

Or via Mint:

mint install realm/SwiftLint

Or as a Swift Package Manager plugin (add to Package.swift):

.package(url: "https://github.com/realm/SwiftLint.git", from: "0.57.0")

Then run:

swift package plugin swiftlint

Basic Usage

Lint Current Directory

swiftlint

This recursively lints all .swift files from the current directory.

Lint a Specific Path

swiftlint lint --path Sources/

Lint Specific Files

swiftlint lint --path Sources/App/ViewModel.swift

Lint from Standard Input

cat MyFile.swift | swiftlint lint --use-stdin --quiet

Agent guidance: When a user says "check my code style" or "lint my Swift code," run swiftlint from the project root. If they point to a specific file or folder, use --path.

Autocorrect

SwiftLint can automatically fix certain violations.

Fix All Autocorrectable Violations

swiftlint --fix

Fix a Specific Path

swiftlint --fix --path Sources/

Fix a Specific File

swiftlint --fix --path Sources/App/ViewModel.swift

Preview What Would Be Fixed (Dry Run)

Lint first to see violations, then fix:

swiftlint lint --path Sources/ && swiftlint --fix --path Sources/

Agent guidance: Always lint before autocorrecting so the user sees what will change. Some violations are not autocorrectable — report those separately after fixing.

Output Formats

Default (Human-Readable)

swiftlint

Output: Sources/App.swift:12:1: warning: Line Length Violation: ...

JSON

swiftlint lint --reporter json

CSV

swiftlint lint --reporter csv

Checkstyle (XML)

swiftlint lint --reporter checkstyle

GitHub Actions

swiftlint lint --reporter github-actions-logging

Xcode Summary (plist)

swiftlint lint --reporter xcode-summary

SonarQube

swiftlint lint --reporter sonarqube

Markdown

swiftlint lint --reporter markdown

Save to File

swiftlint lint --reporter json > swiftlint-results.json

All Available Reporters

Agent guidance: Use --reporter json when you need to parse results programmatically. Use --reporter github-actions-logging on GitHub Actions to get inline annotations on PRs.

Rules

List All Rules

swiftlint rules

Search for a Specific Rule

swiftlint rules | grep "force_cast"

Show Rule Details

swiftlint rules force_cast

Rule Identifiers Quick Reference

Rules fall into categories:

Enabled by Default (Common)

Opt-In (Must Be Explicitly Enabled)

Agent guidance: When setting up SwiftLint for a new project, start with defaults and only add opt-in rules the user specifically requests. Don't overwhelm with every possible rule.

Configuration (.swiftlint.yml)

SwiftLint reads .swiftlint.yml from the current directory (or parent directories).

Generate a Default Config

There's no built-in generator, but here's a minimal config:

# .swiftlint.yml

# Paths to include (default: all Swift files)
included:
  - Sources
  - Tests

# Paths to exclude
excluded:
  - Pods
  - DerivedData
  - .build
  - Packages

# Disable specific rules
disabled_rules:
  - todo
  - trailing_whitespace

# Enable opt-in rules
opt_in_rules:
  - sorted_imports
  - unused_import
  - missing_docs

# Configure specific rules
line_length:
  warning: 120
  error: 200
  ignores_comments: true
  ignores_urls: true

type_body_length:
  warning: 300
  error: 500

file_length:
  warning: 500
  error: 1000

function_body_length:
  warning: 50
  error: 100

identifier_name:
  min_length:
    warning: 2
    error: 1
  max_length:
    warning: 50
    error: 60
  excluded:
    - id
    - x
    - y
    - i
    - j
    - ok

type_name:
  min_length:
    warning: 3
    error: 0
  max_length:
    warning: 50
    error: 60

cyclomatic_complexity:
  warning: 10
  error: 20

nesting:
  type_level:
    warning: 2
  function_level:
    warning: 3

Using a Config from a Custom Path

swiftlint lint --config path/to/.swiftlint.yml

Multiple Configs (Child Config)

# Feature/.swiftlint.yml — inherits parent config and overrides
child_config: ../.swiftlint.yml

disabled_rules:
  - force_cast

Parent Config (Extend from Another)

# .swiftlint.yml
parent_config: shared/.swiftlint-base.yml

Remote Config

parent_config: https://raw.githubusercontent.com/org/repo/main/.swiftlint.yml

Agent guidance: When a project already has .swiftlint.yml, always read it before suggesting changes. Modify the existing config rather than creating a new one.

Inline Rule Management

Disable a Rule for a Line

let value = dict["key"] as! String // swiftlint:disable:this force_cast

Disable a Rule for a Block

// swiftlint:disable force_cast
let a = x as! String
let b = y as! Int
// swiftlint:enable force_cast

Disable All Rules for a Block

// swiftlint:disable all
// Legacy code that can't be refactored yet
// swiftlint:disable:enable all

Disable for Next Line Only

// swiftlint:disable:next force_cast
let value = dict["key"] as! String

Disable for Previous Line

let value = dict["key"] as! String
// swiftlint:disable:previous force_cast

Agent guidance: Prefer targeted disables (disable:this, disable:next) over broad block disables. Never suggest disable all unless the user is dealing with generated code or legacy code they explicitly don't want to lint.

Xcode Integration

Build Phase Script

Add a Run Script Phase in Xcode (Build Phases):

if command -v swiftlint >/dev/null 2>&1; then
  swiftlint
else
  echo "warning: SwiftLint not installed, download from https://github.com/realm/SwiftLint"
fi

Build Phase with Autocorrect

if command -v swiftlint >/dev/null 2>&1; then
  swiftlint --fix && swiftlint
fi

Swift Package Plugin (Xcode 15+)

If SwiftLint is added as a package dependency:

swift package plugin swiftlint

Or in Xcode: right-click the project → "SwiftLintBuildToolPlugin".

Agent guidance: For modern projects (Xcode 15+), prefer the SPM plugin over a build phase script — it pins the SwiftLint version to the project and doesn't require a local install.

CI Integration

GitHub Actions

- name: SwiftLint
  run: |
    brew install swiftlint
    swiftlint lint --reporter github-actions-logging --strict

With only changed files:

- name: SwiftLint Changed Files
  run: |
    git diff --name-only --diff-filter=d origin/main...HEAD -- '*.swift' | \
    xargs -I{} swiftlint lint --path {} --reporter github-actions-logging --strict

Bitrise

- script:
    inputs:
    - content: |
        brew install swiftlint
        swiftlint lint --strict

Jenkins (Checkstyle)

swiftlint lint --reporter checkstyle > swiftlint-checkstyle.xml

Then use the Checkstyle plugin to parse swiftlint-checkstyle.xml.

Analyzing Results

Count Violations by Rule

swiftlint lint --reporter json | python3 -c "
import json, sys, collections
data = json.load(sys.stdin)
counts = collections.Counter(v['rule_id'] for v in data)
for rule, count in counts.most_common():
    print(f'{count:>5}  {rule}')
"

Show Only Errors (Not Warnings)

swiftlint lint --strict 2>&1 | grep "error:"

Strict Mode (Warnings Become Errors)

swiftlint lint --strict

This makes SwiftLint return a non-zero exit code for any violation (not just errors).

Quiet Mode (Errors Only in Output)

swiftlint lint --quiet

Suppresses warnings from output, only shows errors.

Enable/Disable Specific Rules via CLI

swiftlint lint --enable-rules sorted_imports,unused_import
swiftlint lint --disable-rules todo,trailing_whitespace

Custom Rules

Define custom regex-based rules in .swiftlint.yml:

custom_rules:
  no_print_statements:
    name: "No Print Statements"
    regex: "\\bprint\\s*\\("
    message: "Use os_log or Logger instead of print()"
    severity: warning
    match_kinds:
      - identifier

  no_hardcoded_strings:
    name: "No Hardcoded Strings in Views"
    regex: "Text\\(\"[^\"]+\"\\)"
    message: "Use LocalizedStringKey or String(localized:) for user-facing text"
    severity: warning
    included: ".*View\\.swift"

  no_force_unwrap_iboutlet:
    name: "No Force Unwrap IBOutlet"
    regex: "@IBOutlet\\s+(weak\\s+)?var\\s+\\w+:\\s+\\w+!"
    message: "Use optional IBOutlets to avoid crashes"
    severity: error

  accessibility_identifier_required:
    name: "Accessibility Identifier"
    regex: "\\.accessibilityIdentifier\\("
    message: "Good — accessibilityIdentifier found"
    severity: warning
    match_kinds:
      - identifier

  prefer_logger_over_print:
    name: "Prefer Logger"
    regex: "\\bNSLog\\s*\\("
    message: "Use Logger (os.Logger) instead of NSLog"
    severity: warning

Match Kinds

Agent guidance: Custom rules are powerful but regex-based — they can produce false positives. Always test custom rules on the codebase before suggesting them as permanent additions.

Common Flags Reference

Common Workflows

Set Up SwiftLint for a New Project

# 1. Install
brew install swiftlint

# 2. Run initial lint to see baseline
swiftlint lint --path Sources/ --reporter json > baseline.json

# 3. Create config based on results
cat > .swiftlint.yml << 'EOF'
included:
  - Sources
  - Tests
excluded:
  - Pods
  - DerivedData
  - .build
disabled_rules:
  - todo
opt_in_rules:
  - sorted_imports
  - unused_import
line_length:
  warning: 120
  error: 200
  ignores_urls: true
EOF

# 4. Fix autocorrectable issues
swiftlint --fix --path Sources/

# 5. Re-lint to see remaining issues
swiftlint

Fix All Issues Before a PR

# Autocorrect what we can
swiftlint --fix

# Check what remains
swiftlint lint --strict

Lint Only Changed Files (vs. main)

git diff --name-only --diff-filter=d origin/main...HEAD -- '*.swift' | \
  xargs -I{} swiftlint lint --path {} --strict

Compare Violation Counts Between Branches

# Current branch count
CURRENT=$(swiftlint lint --quiet 2>&1 | wc -l | tr -d ' ')

# Main branch count
git stash
git checkout main
MAIN=$(swiftlint lint --quiet 2>&1 | wc -l | tr -d ' ')
git checkout -
git stash pop

echo "main: $MAIN violations, current: $CURRENT violations"

Troubleshooting

Common Errors

Performance Tips

• Always exclude Pods/, DerivedData/, .build/, and Packages/ in config
• Use --cache-path to persist cache across CI runs
• Lint only changed files on CI instead of the entire project
• Use --no-cache only when debugging unexpected results

Notes

Agent Tips

When a user asks to "clean up" or "fix style" in Swift code, run swiftlint --fix first, then swiftlint lint to report remaining issues.

Before adding SwiftLint to an existing project, run swiftlint lint --reporter json to assess the violation count. If there are hundreds of violations, suggest a phased approach: fix autocorrectable ones first, then tackle the rest by category.

Always check for an existing .swiftlint.yml before creating one. Read it to understand the team's style preferences.

For projects targeting accessibility (which should be all of them), suggest enabling accessibility_label_for_image and accessibility_trait_for_button opt-in rules.

When the user's project uses SwiftUI, suggest a custom rule to catch hardcoded strings in Text() views — all user-facing strings should use String(localized:) for localization support.

The --strict flag is essential for CI — without it, SwiftLint exits 0 even with warnings, which means your CI pipeline won't catch style regressions.