SwiftLint Reference

Kip Landergren

(Updated: )

My cheat sheet for Realm’s SwiftLint static analysis tool covering installation, configuration, and usage.

Contents

SwiftLint Version Note

The following document refers to SwiftLint version 0.39.1.

Resources

Code

Documentation

Installation

Via homebrew:

$ brew install swiftlint

From source, editing Makefile beforehand as appropriate:

$ make install

Command Line Usage

Get help information, including a list of commands:

$ swiftlint help

Get help information about a specific command, e.g. lint:

$ swiftlint help lint

Get information about a specific rule, e.g. empty_parameters:

$ swiftlint rules empty_parameters

Pass an alternative configuration file:

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

Xcode Integration

Add a Run Script build phase to your target invoking swiftlint.

Instructions

Sample Build Phase Code

if which swiftlint >/dev/null; then
  swiftlint
else
  echo "warning: SwiftLint not installed!"
fi

Sample Configuration

Create $PROJECT_ROOT/.swiftlint.yml containing:

disabled_rules:
  - line_length

Refer to Configuration section for more options available.

Rules

SwiftLint rules have three dimensions of organization:
Kind reflecting one of the categories idiomatic, lint, metrics, performance, or style
Type whether the rule is applied via commands lint or analyze
State where the rule is on-by-default or opt-in

Kinds

Refer to values of the RuleKind enum.
idiomatic rules the Swift community / Apple have largely standardized on
lint rules uncovering potential bugs or quality issues
metrics rules ensuring project does not explode in scope
performance rules where replaced code may be more performant
style rules that are a matter of preference

Type

The majority of rules are lint rules. As of version 0.37.0 the only AnalyzerRule rules are:

State

A rule appears to be marked on-by-default only when there is sufficient consensus from the Swift community and there is no significant performance impact of its running.

List of Available Rules

A list of rules may be viewed in the repository’s Rules.md or locally via the generate-docs command:

$ swiftlint generate-docs > local-rules.md

Custom Rules

Custom rules are supported and best explained in the SwiftLint README.

Configuration

By default SwiftLint reads $PROJECT_ROOT/.swiftlint.yml for configuration options and will respect per-directory configuration files (also called “nested configuration”).

An alternative configuration file may be passed via:

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

The following configuration directives represent lists taking rule identifiers as members:
opt_in_rules a list of opt-in rules that are enabled
disabled_rules a list of rules that are disabled
analyzer_rules a list of rules run by swiflint analyze
whitelist_rules a list of the only rules to enable

Note: certain rules have corresponding opposites, with only one of them enabled typically being desired enabled.

Some rules are parameterized such that they can be configured for behavior, thresholds, and other properties. e.g. trailing_comma behavior configuration for requiring trailing commas:

trailing_comma:
  mandatory_comma: true

Refer to the rule implementation to determine how to configure.

The paths included or excluded are controlled via configuration directives:
included a list of paths to include in processing
excluded a list of paths to exclude from processing

Controlling SwiftLint

From within source code on a per-rule basis, e.g. for rule identifier_name:

// swiftlint:disable identifier_name
let a = 0
// swiftlint:enable identifier_name

Including various degrees of advanced control, e.g. for rule identifier_name:

// swiftlint:disable:next identifier_name
let a = 0
let b = 0 // swiftlint:disable:this identifier_name
let c = 0 // error generated on this line
let d = 0
// swiftlint:disable:previous identifier_name

And a “big hammer” approach:

// swiftlint:disable all
let a : Int = 0
// swiftlint:enable all

Note that multiple rules are supported through successive declarations separated by a space:

// swiftlint:disable:next rule_identifier_1 rule_identifier_2