A step-by-step guide to installing SwiftFormat, running it against an iOS codebase, and committing a shared configuration your whole team can rely on.
SwiftFormat runs on macOS as a command-line tool and as an Xcode Source Editor extension. To follow this guide you will want a Mac with Xcode installed and a Swift project under Git version control.
Version control is not optional here. SwiftFormat rewrites your source files in place, so having a clean Git working tree means you can review exactly what changed and revert instantly if something looks wrong.
Starting from a clean tree is the single most important safety habit in this whole process. If the working directory already has uncommitted edits, the formatting diff mixes with your own changes and becomes hard to reason about.
A quick reminder on scope. Installing SwiftFormat gives you a formatter. It will not build, sign, or ship your app, and it does not replace Xcode.
It simply makes your Swift code consistent before you build. Keep that boundary in mind so your expectations match what the tool actually delivers, and plan the rest of your release pipeline separately.
The most common way to install SwiftFormat on a Mac is with Homebrew, the popular macOS package manager. If you already use Homebrew, installing is a single command in Terminal.
Run `brew install swiftformat`. Homebrew downloads and installs the tool along with anything it needs, and afterward the `swiftformat` command is available in your shell.
Homebrew is the fastest path for a first setup because it handles the download, placement, and future upgrades for you. Later, running `brew upgrade swiftformat` keeps you current.
The project's official GitHub page documents other installation methods too, including building from source and integrating the tool per-project so every contributor uses the same version. Pinning a specific version per project is worth considering for larger teams, because it removes the chance of two developers formatting the same file differently.
For a first setup, Homebrew is the fastest path. Consult the official README if you need an alternative for your environment or a reproducible, version-locked install.
After installing, confirm that the tool is on your PATH and runnable. In Terminal, run `swiftformat --version`.
If you see a version number printed back, the installation succeeded. If instead you see something like `command not found`, your shell cannot locate the binary, which usually means a PATH or installation issue you will need to resolve before continuing.
That error is extremely common on fresh machines and is almost always about environment configuration rather than a broken tool. Opening a new Terminal window often resolves it if the install just finished.
It is worth also skimming `swiftformat --help`. That output lists the available options and gives you a feel for how the tool is invoked, which makes the following steps easier to understand.
Taking a minute here saves confusion later. A tool you have confirmed is installed and reachable is much easier to reason about than one you are only assuming works.
Before letting SwiftFormat rewrite anything, preview what it would change. The tool supports a mode that reports which files would be modified without actually editing them.
Running a dry run against your project shows the blast radius of formatting an existing codebase. On a large legacy project, that list can be long, and knowing this in advance helps you plan the rollout.
A long list is not a warning sign in itself; it simply reflects how far the current code sits from your chosen style. What matters is that you see it before it happens rather than after.
This is a habit worth keeping. Any time you change your rule set, a dry run tells you the impact before you commit to it.
Check the official documentation for the exact flag, since options can evolve between versions. Reading the current help output for your installed version is the safest way to confirm the precise invocation.
When you are ready, run SwiftFormat against your source directory. Pointing it at your project folder, for example `swiftformat .` from the project root, formats the Swift files it finds there according to the default rules.
Because you are in a clean Git working tree, the result is a diff you can inspect. Open it in your editor or with `git diff` and look through the changes.
Skim rather than scrutinise every line. The goal is to confirm the changes are the expected mechanical adjustments, not to review each individual edit, which would defeat the purpose of automation.
For a first run on an existing project, treat this as its own commit. A dedicated 'apply SwiftFormat' commit keeps the large mechanical change separate from feature work, which makes history easier to read and code review far less painful.
It also helps anyone using tools like git blame, because a single, clearly labeled formatting commit is easy to skip over when tracing the real history of a line.
The default style is a fine starting point, but teams usually want their own preferences. SwiftFormat reads a plain-text configuration file, conventionally named .swiftformat, placed at your project root.
In that file you enable or disable specific rules and set options. Because the file lives in your repository, every contributor and every CI run uses the exact same settings automatically.
That automatic sharing is the real value. Nobody has to remember flags or replicate settings by hand; cloning the repo is enough to inherit the team's style.
Start small. Adopt the defaults, then adjust only the handful of rules your team feels strongly about.
The official Rules reference documents what each rule does, so you can make informed choices rather than guessing. Commit this file alongside your first formatting commit so the configuration and its effects land together.
If your team prefers working inside Xcode, install the SwiftFormat Source Editor extension. This lets developers format the current file directly from Xcode's Editor menu without dropping to the terminal.
The extension comes from a separate macOS app, not from the Homebrew CLI install. Installing the command-line tool alone will not add the Editor menu item, which surprises many first-time users.
Source Editor extensions must be enabled in System Settings under the Extensions section before they appear in Xcode. This is a one-time step per machine, and it is a common stumbling block, so make sure teammates know to do it.
The CLI and the extension are complementary. Many developers use the extension for quick in-editor formatting during the day and rely on the CLI or a commit hook to enforce consistency across the whole project.
If you go this route, point the extension at the same configuration your command-line runs use, so in-editor formatting matches what lands on commit.
With the tool installed, the code formatted, and a .swiftformat file in place, commit everything and push. Now anyone who clones the repository inherits your style rules.
Document the setup briefly in your project's README. A short note telling contributors to install SwiftFormat and how the configuration works saves a lot of onboarding time.
Include the exact install command and a line about enabling any automation, so a new teammate can be productive without asking. Good documentation here pays for itself the first time someone joins.
Remember the boundary of what you have accomplished. Your code is now consistently formatted and that consistency is enforceable across the team.
Shipping the app itself is a separate process that still requires Xcode, a real build and signing pipeline, and an Apple Developer Program membership. Installing and configuring a formatter is a valuable first step, but it is only one part of a complete release workflow.
The most common method is Homebrew with the command brew install swiftformat. The official GitHub README documents additional installation options, including building from source and per-project integration.
Run swiftformat --version in Terminal. A printed version number means it installed successfully; command not found indicates a PATH or installation problem.
Create a plain-text file named .swiftformat at your project root, enable or disable rules there, and commit it so every contributor and CI run uses the same settings.
Format on a clean Git working tree and make the initial formatting its own separate commit, so the large mechanical change does not mix with feature work.
No. SwiftFormat only formats source code. Publishing still requires Xcode to build and sign, plus an Apple Developer Program membership.