Swiftlint

# Adoption and Configuration

Detailed guidance on installing SwiftLint, configuring `.swiftlint.yml`, and rolling out linting in existing codebases.

## Contents

- [Installation Paths](#installation-paths)
- [Configuration File Discovery](#configuration-file-discovery)
- [Configuration Deep Dive](#configuration-deep-dive)
- [Severity Tuning](#severity-tuning)
- [Environment Variable Interpolation](#environment-variable-interpolation)
- [Nested and Child Configurations](#nested-and-child-configurations)
- [Remote Configuration](#remote-configuration)
- [Rollout Strategy for Existing Codebases](#rollout-strategy-for-existing-codebases)

---

## Installation Paths

| Method | When to use |
| -------- | ------------- |
| **SwiftLintPlugins SPM package** | Default for any project with `Package.swift`. Pins version automatically. |
| **Homebrew** (`brew install swiftlint`) | CI runners, pre-commit hooks, standalone CLI usage. |
| **Mint** (`mint install realm/SwiftLint`) | Teams using Mint for tool management. |
| **CocoaPods** (`pod 'SwiftLint'`) | Legacy projects already using CocoaPods. Binary is at `${PODS_ROOT}/SwiftLint/swiftlint`. |
| **Pre-built binary** | Download from [GitHub releases](https://github.com/realm/SwiftLint/releases). Useful for controlled CI environments. |

The build tool plugin (via `SwiftLintPlugins`) is recommended over all other local integration methods. See the plugins and integrations reference linked from SKILL.md for setup details.

## Configuration File Discovery

SwiftLint treats the top-level `.swiftlint.yml` as the main configuration, then optionally merges the nearest nested `.swiftlint.yml` found while walking up from an individual file.

- If no config is found, SwiftLint uses its built-in defaults.
- A project root config applies to all files unless a nested config refines it for a subtree.
- At most one nested `.swiftlint.yml` is merged for any given file.
- Passing `--config` overrides automatic discovery entirely and disables nested-config lookup.

Working directory behavior:
- The build tool plugin uses the topmost `.swiftlint.yml` within the package/project directory as its working directory, and falls back to the package/project root if no config file is found there.
- Run scripts use `${SRCROOT}` or the Xcode build setting for the working directory.
- CLI invocations use the shell's current directory.

## Configuration Deep Dive

### Rule control keys

```yaml
# Enable defaults minus these:
disabled_rules:
  - trailing_whitespace
  - todo

# Add these on top of defaults:
opt_in_rules:
  - empty_count
  - closure_spacing
  - sorted_imports
  - vertical_whitespace_opening_braces
  - contains_over_filter_count
  - first_where
  - last_where
  - modifier_order
```

`only_rules` is mutually exclusive with `disabled_rules` and `opt_in_rules`. Use it only when you want to start from an empty rule set and explicitly list every rule:

```yaml
only_rules:
  - line_length
  - force_cast
  - force_try
```

### Analyzer rules

Analyzer rules require passing compiler logs to SwiftLint. They are not included in default or opt-in sets:

```yaml
analyzer_rules:
  - unused_import
  - unused_declaration
```

See the custom rules and analyze reference linked from SKILL.md.

### Path control

```yaml
included:
  - Sources
  - Tests

excluded:
  - .build
  - DerivedData
  - Carthage
  - Pods
  - "**/Generated"
  - "**/Snapshots"
```

`included` and `excluded` support glob patterns. Paths are relative to the config file's directory.

### Reporter

```yaml
reporter: xcode    # default — Xcode-compatible warnings/errors
# reporter: json
# reporter: sarif
# reporter: checkstyle
# reporter: csv
# reporter: emoji
# reporter: github-actions-logging
```

Use `sarif` for GitHub code scanning integration. Use `json` for custom tooling. Use `github-actions-logging` for inline PR annotations without SARIF upload.

### Global modifiers

```yaml
strict: true       # all warnings become errors
# lenient: true    # all