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?
answer
- on demand, every build, or when invoked
- the host app holds the extension's rules
- re-import after editing .swiftformat
- a formatting build phase clears undo
- a command plugin never runs during a build
basics
~20 sThe 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 sThe **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# 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.1go deeper
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.
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.
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.
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.