airbnb/swift: A Style Guide That Ships as a Swift Package Manager Command Plugin

The problem: style debates that never end in a diff

The README states the goal plainly: keep discussions on diffs focused on the code's logic rather than its style. That is the whole pitch. A written guide alone does not achieve it, because a reviewer still has to notice the violation and write a comment. The project's answer is to pair the prose with tooling, and it sets an explicit constraint on which rules get to be tooling: "Most rules should be autocorrectable using SwiftFormat." If a rule purely affects syntax, the guide says it must be autocorrectable. Linting is reserved for rules that change runtime behavior or discourage patterns with no direct replacement, because those cannot be fixed by a formatter without altering what the code does.

That split matters for who this is for. It is aimed at teams large enough that unfamiliar code is a daily problem, and disciplined enough to accept a formatter rewriting their files. A solo developer writing an app alone gets less from it; a team of fifteen reviewing each other's pull requests gets the diff-noise reduction the README is describing. The guide also says it sits on top of the official Swift API Design Guidelines and should not contradict them, so it is an addition to Apple's document, not a replacement.

How the rules become a runnable command

The repository is Markdown-first, but the enforcement path is a Swift Package Manager command plugin. The layout confirms this: `Package.swift`, a `Plugins/` directory, `Sources/`, `Tests/`, and two configuration files at the root, `airbnb.swiftformat` and `swiftlint.yml`. Those two files are where the actual rule configuration lives, and the plugin wires them to the tools.

The plugin infers your package's minimum Swift version from the `swift-tools-version` declared in your `Package.swift`, which is a sensible default and also a trap: if your manifest declares an older tools version than the language features you use, formatting decisions may not match your build. The `--swift-version` flag exists to override that inference.

Exit codes are the part worth reading twice. The README states the plugin returns a non-zero exit code when there is a lint failure that requires attention, and then draws a distinction: in `--lint` mode any failure from any tool fails the run, while in standard autocorrect mode only SwiftLint lint-only rules fail it. In other words, a plain `swift package format` will rewrite your files and still succeed even if the formatter had to change things, because the change was the point. Only rules that cannot be autocorrected break the build.

Installing the plugin and running your first format

There is no standalone binary to download. The README's install path is to add this repository as a package dependency, then invoke the command plugin from your package directory. Add the dependency to your `Package.swift`:

dependencies: [
  .package(url: "https://github.com/airbnb/swift", from: "1.0.0"),
]

Then run the plugin. The first invocation prompts for permission to write to the package directory, which is Swift Package Manager's normal sandbox behavior for command plugins:

$ swift package format

In a noninteractive shell such as CI, the prompt cannot be answered, so the README gives the explicit form:

$ swift package --allow-writing-to-package-directory format

To check without rewriting anything, add `--lint`. This is the mode you want on a pull request, because it fails on any lint failure from any tool:

$ swift package format --lint

Scope is controllable. By default the plugin runs on the entire package directory; `--exclude Tests` skips a directory, and `--paths Sources Tests Package.swift` or `--targets AirbnbSwiftFormatTool` narrows the run to explicit paths or SPM targets. If the inferred Swift version is wrong, pass `--swift-version 6.2`. After the first successful run, expect a large diff on an existing codebase; that diff is the formatter applying the autocorrectable rules, and it is the moment to decide whether you accept the churn.

The 100 versus 130 column rule is a deliberate compromise

The Xcode Formatting section says each line should have a maximum column width of 100 characters, justified by larger screen sizes. Then it admits the tooling only strictly enforces 130. The README's own explanation is that this limits manual cleanup for reformatted lines that fall slightly above the threshold.

That is an honest trade-off and also the guide's clearest limitation. A rule that says 100 but enforces 130 is a rule reviewers must police by hand for everything between those two numbers. If your team wants a hard gate at 100, this configuration will not give it to you. The same section also specifies 2-space indentation and trimming trailing whitespace, both mapped to SwiftFormat rules, and points at a script in `resources/xcode_settings.bash` for enabling matching Xcode settings, which the README suggests running as part of a Run Script build phase. Note that Xcode settings and the command plugin are separate mechanisms: the plugin formats files, the script configures the editor, and nothing in the README makes one depend on the other.

Where the guide stops being automatable

Not every rule can be a formatter directive, and the guide does not pretend otherwise. The naming section is the clearest example. It requires UpperCamelCase for types and protocols and lowerCamelCase for everything else, with a documented exception: a private property may be prefixed with an underscore when it backs an identically named property or method at a higher access level. The README gives two cases where that helps, type erasure and backing a less specific type with a more specific one, and shows a view controller storing a `CustomView` in `_view` because `UIViewController` already owns `view`.

No formatter can decide whether your underscore is justified. This is exactly the category the guiding tenets describe as best practices without autocorrect or linting, welcomed as advice for humans and AI agents. The repository reflects that with an AI skill at `swift.airbnb.tech/skill` that summarizes the non-autocorrected best practices. So the enforcement story has three tiers, not one: SwiftFormat autocorrects syntax, SwiftLint catches behavioral patterns, and a remainder of rules depends on a human or an agent reading the guide. Teams that assume the plugin covers everything will be surprised by what it silently leaves alone.

Alternatives and what actually differs

The obvious comparison is SwiftFormat on its own. SwiftFormat is the engine this guide configures; the repository even ships an `airbnb.swiftformat` file and links each rule to its SwiftFormat rule page. Adopting SwiftFormat directly means you choose every option yourself and own the resulting configuration, with no prose explaining why a rule exists and no shared baseline to point at in a review. Adopting airbnb/swift means inheriting Airbnb's choices, including the 100/130 split, and getting a document that argues for each one.

The second comparison is SwiftLint on its own, which the repository also ships a `swiftlint.yml` for. SwiftLint is a linter, and the guide's own tenets explain why linting is the wrong tool for pure formatting: it reports rather than fixes, and the README notes linting is best suited to rules affecting runtime behavior. Running both tools by hand is possible, but then you maintain two configs and a wrapper script; the plugin's value is that `swift package format` invokes the pair with one exit-code contract. If you already have a mature in-house configuration, the migration cost is real and the guide offers no automated path from your rules to its rules.

Maintenance, licence and upgrade cost

The last push to the default branch was on 2026-09-21, and the most recent release listed is 1.2.0 from 2025-12-20, following 1.1.0 in August 2025 and 1.0.8 in January 2025. The repository is not archived. The README's dependency example pins `from: "1.0.0"`, which under Swift Package Manager semantics allows any 1.x upgrade, so a `swift package update` can move you to a new minor version and change formatting output. Because formatting changes produce diffs across the whole codebase, treat a version bump as a scheduled event rather than something that arrives with an unrelated dependency update; pinning an exact version is the way to control that, at the cost of missing fixes.

The licence is MIT, stated in `LICENSE.md`. MIT is permissive, so reusing the configuration files and adapting the guide internally is broadly permitted, but this is not legal advice and the usual caveat applies: if you redistribute the guide or its configs inside a product, have counsel read the licence text rather than a summary of it. The Markdown content itself is the project's writing, so copying it verbatim into internal documentation carries attribution expectations that the MIT text spells out.

Editorial conclusion

Adopt it if your team already runs SwiftFormat or SwiftLint and wants one shared configuration instead of a homegrown ruleset; the plugin's `--lint` mode makes it usable in CI without writing wrapper scripts. Skip it if you cannot accept a 100-character line guideline that is only strictly enforced at 130, or if your codebase is not a Swift package, since the documented entry point is the SPM command plugin. Before rolling it out, run `swift package format --lint` on a branch and read the diff, then check whether your `swift-tools-version` matches the Swift version you actually build against, because the plugin infers the minimum Swift version from that field unless you pass `--swift-version`.

Frequently asked questions

Official sources

1. airbnb/swift on GitHub
2. License: MIT
3. Project website
4. README
5. Releases