Learn how to tailor SwiftFormat to your team's style using a version-controlled .swiftformat configuration file, enabling and disabling rules with confidence.
SwiftFormat ships with a sensible default style, and for many projects the defaults are enough. But most teams eventually want to reflect their own conventions, and that is where configuration comes in.
A shared configuration turns 'my preference' into 'our rule'. Once it is committed, the tool enforces the same choices for everyone, ending the debate about how code should look.
That shift from opinion to enforced convention is the quiet superpower of a config file. Arguments that used to recur in every code review simply stop, because the answer is codified and applied automatically.
The goal of this guide is to show how to configure SwiftFormat deliberately, so your rule set is intentional and documented rather than a pile of copied snippets nobody understands.
A configuration you understand is one you can maintain. A configuration copied blindly from elsewhere tends to cause surprises the first time it reformats something you did not expect.
SwiftFormat reads its configuration from a plain-text file, conventionally named .swiftformat, placed at the root of your project. When you run the tool from that directory, it picks up the file automatically.
The file contains options and rule selections, one per line, in a simple format. Because it is plain text and lives in your repository, it is version-controlled like any other source file.
That version control is the whole point. When a teammate clones the repo or CI runs the formatter, everyone gets identical behavior with no manual setup.
Changes to your style are reviewed through pull requests just like code. That means a style decision is discussed, approved, and recorded, rather than living only in one person's head or local settings.
Keeping the file at the project root also lets SwiftFormat find it without extra flags, which keeps your commands and your automation simple.
SwiftFormat distinguishes between rules and options, and understanding the difference makes configuration much clearer. Rules are the individual transformations the tool can apply, such as removing redundant self or organizing imports.
Options are the settings that control how certain rules behave, for example the indentation width or how arguments are wrapped. A rule decides whether a transformation happens; an option tunes the details of it.
Once that mental model clicks, the configuration file stops looking like an arbitrary list and starts reading like a set of deliberate decisions. You are choosing which transformations run, then shaping how the active ones behave.
The official Rules reference documents every rule by name, along with a description and examples. Keep that page open while configuring.
It is the authoritative source for what each rule actually does, and it prevents you from enabling something whose effect you do not fully understand. When a rule and an option interact, the reference is also where you confirm which options apply to which rule.
You control which rules run by enabling or disabling them in your configuration. Some rules are on by default, and you may want to turn a few off; others are opt-in, and you enable the ones your team wants.
A good practice is to change one thing at a time. Adjust a rule, run SwiftFormat, and review the resulting diff before moving on.
This incremental approach keeps you in control. If a rule produces changes you dislike, you know exactly which setting caused it and can revert just that one change rather than untangling a dozen simultaneous edits.
Batching many rule changes into a single commit feels efficient but backfires the moment one of them misbehaves, because you cannot tell which one is responsible. Small, isolated steps are slower to type and far faster to debug.
It also makes your commit history a useful record. Each configuration change lands with the reformatting it caused, so a future teammate can see not just what the rule does but what it actually did to your codebase.
Options let you fine-tune formatting details. If your team indents with a specific number of spaces or has a preferred way of wrapping long function calls, options are how you express that.
The safest way to discover available options is the tool's own help output and the official documentation. Rather than guessing option names, read what is supported for your version.
Option names and defaults can shift between releases, so checking the help for the version you actually have installed is more reliable than trusting an old example. This small verification step avoids silent no-ops from a misspelled or renamed option.
Set only the options you care about and leave the rest at their defaults. A lean configuration is easier to understand and maintain than one that redundantly specifies every possible setting.
Minimalism here is a feature, not a compromise. Every option you set is something a future maintainer has to understand, so specifying only what genuinely matters keeps the file readable.
Occasionally you will have a section of code that should not be reformatted, such as a carefully aligned table of data. SwiftFormat supports inline comment directives that disable formatting for a specific region of a file.
Use these sparingly. Each exception is a small deviation from your consistent style, and too many of them undermine the reason you adopted a formatter in the first place.
A codebase riddled with disable directives is barely more consistent than one with no formatter at all. Reserve the escape hatch for genuine cases where automated formatting actively harms readability.
When you do use one, a brief comment explaining why helps the next developer understand that the deviation is intentional. Without that note, a well-meaning teammate may simply delete the directive, assuming it was a mistake.
The official documentation describes the exact directive syntax, so refer to it for the current form. Because the syntax can change between versions, treating the docs as the source of truth is safer than copying a directive from an old blog post.
If you also use SwiftLint, configuration becomes a coordination exercise. SwiftFormat and SwiftLint can both have opinions about the same stylistic details, and when they disagree they will fight, each undoing the other's work.
The fix is to draw a clear boundary. Let SwiftFormat own formatting concerns, and disable any SwiftLint rules that duplicate what the formatter already handles.
Framing it as ownership makes the resolution obvious. Wherever the two overlap on a purely stylistic decision, the formatter is the authority and the corresponding linter rule is switched off.
Done well, the two tools complement each other cleanly. SwiftFormat guarantees consistent layout, while SwiftLint focuses on the code-quality and convention checks that a formatter does not attempt.
Document which tool owns what so future contributors do not reintroduce conflicts. A short note in the repository explaining the division of responsibility can save hours of confusion the next time someone updates either tool.
Before you commit a new or updated configuration, run SwiftFormat across the whole project and review the diff. This confirms your settings produce the result you expect and surfaces any surprises.
Commit the .swiftformat file together with the formatting changes it produces. Bundling them keeps history coherent, since the config change and its effects land together.
Separating them into different commits creates a confusing intermediate state where the config says one thing but the code has not yet caught up. Keeping them together avoids that mismatch entirely.
Finally, keep expectations realistic. A tuned configuration makes your codebase consistent and pleasant to read, but it is still just formatting.
It does not affect whether your app builds correctly, and it has nothing to do with signing or App Store submission, which remain the job of Xcode and the Apple Developer Program. A great configuration is worth the effort, but it is one piece of a much larger development and release process.
It is a plain-text configuration file placed at your project root where you enable or disable rules and set options. SwiftFormat reads it automatically and it is version-controlled with your code.
Rules are the individual transformations the tool can apply, while options tune how certain rules behave, such as indentation width. Rules decide whether a change happens; options control its details.
SwiftFormat supports inline comment directives that disable formatting for a region of a file. Use them sparingly and check the official documentation for the current syntax.
Draw a clear boundary: let SwiftFormat own formatting and disable any SwiftLint rules that duplicate it, so the two tools do not repeatedly undo each other's changes.
The official Rules reference on GitHub documents each rule by name with descriptions and examples. Keep it open while configuring to avoid enabling rules whose effects you do not understand.