skip to content

How do SwiftFormat's Xcode source editor extension, a Run Script build phase and its command plugin differ in which configuration they use and when they run?

level: seniorimportance: nice to knowfreq 22%

answer

  1. on demand, every build, or when invoked
  2. the host app holds the extension's rules
  3. re-import after editing .swiftformat
  4. a formatting build phase clears undo
  5. a command plugin never runs during a build

basics

~20 s

The source editor extension formats the open file on demand using rules stored in its host app, not the project's .swiftformat. A Run Script phase runs the CLI on every build; the command plugin only when invoked.

solid answer

~40 s

The **SwiftFormat for Xcode** extension adds Format File, Format Selection and Lint File under Xcode's Editor menu. It uses rules and options saved in its host app, imported from a `.swiftformat` through the app's File menu and never refreshed automatically, and it takes indent width and tabs from Xcode's own text settings. A **Run Script phase** runs the command-line tool on every build against the project's `.swiftformat`; the README pins the version through a small `BuildTools` package, places the phase above Compile Sources with Based on dependency analysis unchecked, and warns that rewriting sources during a build clears undo history, so many teams run `--lint --lenient` there instead. The **command plugin**, `swift package plugin --allow-writing-to-package-directory swiftformat`, or the plugin menu in Xcode, reads the package root's `.swiftformat` and runs only when someone invokes it.

code

bash · 5 lines
bash
# Run Script phase, placed above Compile Sources: pinned version, report only
swift run -c release --package-path BuildTools swiftformat --lint --lenient "$SRCROOT"

# Command plugin, run on demand for one target of a Swift package
swift package plugin --allow-writing-to-package-directory swiftformat --target PetCatalog --swift-version 6.1

go deeper

for a junior

Recall the three integrations: the Editor menu extension, a Run Script build phase and the swiftformat command plugin, and that only the latter two read the project's .swiftformat.

for a middle

Explain why the extension needs its configuration re-imported, how the README's BuildTools package pins the version, and why the phase sits above Compile Sources.

for a senior

Pick lint-only build phases to avoid undo loss, pin one version for everyone, and keep enforcement in the command-line tool rather than the extension or the plugin.

for a principal

Decide where formatting is enforced versus offered as convenience, so every developer and CI job formats with one pinned version and one committed configuration.

## Three ways into Xcode SwiftFormat offers three integrations that look interchangeable but differ in two ways that matter: **which configuration they read** and **when they run**. | Integration | Configuration it reads | When it runs | |---|---|---| | SwiftFormat for Xcode source editor extension | rules and options saved in its host app | when a developer picks an Editor menu command | | Run Script build phase | the project's `.swiftformat` files, like the command line | on every build of the target it is in | | `swiftformat` command plugin | the package root's `.swiftformat` and any arguments passed | only when invoked from the command line or Xcode | ## The source editor extension Installed as the **SwiftFormat for Xcode** app, the extension appears under Xcode's Editor menu with three commands: **Format File**, **Format Selection** and **Lint File**. - It does **not** read the project's `.swiftformat`. Rules and options live in the host app, and a project's file must be imported through the app's File menu. - There is no per-project setting. Switching between projects means importing a different file, and the extension cannot notice when a `.swiftformat` it imported later changes; it must be re-imported. - Indent width and tabs versus spaces come from Xcode's text settings for the file being edited, not from `--indent`. - A file-header template that needs file details, such as `{file}` or `{created}`, is not applied by the extension. - Since 0.64.0, formatting in Xcode preserves editor lines that did not change. It is the right tool for a developer who wants to tidy a file while typing; it is the wrong tool to enforce anything, since every machine can hold different imported settings. ## A Run Script build phase The README's recommended setup keeps the version under source control: 1. Create a `BuildTools` folder beside the `.xcodeproj` with a `Package.swift` depending on SwiftFormat `from: "0.64.0"`, plus an empty `Empty.swift`. 2. Add a Run Script phase to the app target, uncheck **Based on dependency analysis**, and drag it **above** Compile Sources. 3. Run `swift run -c release --package-path BuildTools swiftformat "$SRCROOT"` in it. Three traps come with it: - **Rewriting sources while you edit them clears Xcode's undo history.** The README suggests putting the phase in the test target, or running SwiftFormat in lint mode in the main build and formatting at another moment; adding `--lenient` makes that lint step only print warnings in Xcode's issue list. - **A phase that calls whatever `swiftformat` is on the `PATH`** lets teammates' versions differ and reformat each other's code. On Apple silicon, Homebrew installs to `/opt/homebrew/bin`, so the README's script adds that folder to `PATH` before calling `swiftformat`. - **User script sandboxing.** The README says this SwiftPM-based script needs Xcode's `ENABLE_USER_SCRIPT_SANDBOXING` set to NO; how that setting works for build phases in general is covered with Xcode. As of 0.64.0 the repository no longer includes a prebuilt binary and new releases are no longer distributed through CocoaPods, so a phase that ran a binary from a CocoaPods install stays on an old version until it moves to the package or a release download. ## The command plugin SwiftFormat's package declares a **command plugin** with the verb `swiftformat` and permission to write to the package directory. - From the command line: `swift package plugin --allow-writing-to-package-directory swiftformat`, optionally with `--target MyLibrary` and SwiftFormat arguments such as `--swift-version 6.1`. - From Xcode 14 or later, the plugin can be run on a Swift package or an Xcode project; for a project, SwiftFormat processes the project's main directory and ignores `--target`. - It honours a `.swiftformat` in the package root. Because it is a command plugin rather than a build tool plugin, **no build ever runs it**. That makes it a deliberate "format now" action, not an enforcement point. How SwiftPM plugins are declared, sandboxed and granted permissions is covered with Swift Package Manager. ## Choosing a combination - **Enforcement** comes from the command-line tool at one pinned version: a Run Script phase, a pre-commit hook or a CI `--lint` step. - **Convenience** comes from the extension or the plugin, which developers trigger when they choose. - Whatever runs, make it read the same committed `.swiftformat`; the extension is the one integration that cannot, so re-import the file when it changes.

  • A developer edited the project's .swiftformat, but Format File in Xcode still applies the old rules; why?
    The source editor extension never reads the project's file directly; it uses the configuration stored in the SwiftFormat for Xcode host app, and it cannot detect changes to a file it imported earlier. Re-import the updated `.swiftformat` through the host app's File menu. Each developer has to do this, which is why the extension is a convenience, not the team's enforcement point.
  • How do you get SwiftFormat feedback inside Xcode builds without the build rewriting files and clearing undo history?
    Run the pinned tool in lint mode in the Run Script phase: `swiftformat --lint --lenient "$SRCROOT"`. It prints each needed change as a warning in Xcode's issue list and exits 0, so the build continues and no file changes. Actual formatting then happens on demand, in a pre-commit hook, or in a phase on the test target, as the README suggests.

  • The Xcode extension picks up the project's .swiftformat automatically.
  • SwiftFormat's package plugin runs on every build like a build tool plugin.
  • A formatting Run Script phase is harmless while you are editing files.
  • The extension's host app setting decides the indent width Xcode formats with.
  • Put the Run Script phase after Compile Sources so it cannot slow the compile.

Assumes SwiftFormat 0.64.0, which dropped the in-repository prebuilt binary and CocoaPods releases and made the Xcode extension preserve unchanged editor lines.