Why should a project give SwiftFormat its Swift version with --swift-version or a .swift-version file, and what goes wrong without one?
answer
- some rules need newer syntax
- unset means version-gated rules stay off
- the warning every run prints
- trailing commas in argument lists need 6.1
- the oldest compiler that builds the project
basics
~20 sSome SwiftFormat rules produce syntax only newer Swift accepts, so with no version set they stay off and every run warns. Declare the oldest Swift compiler that builds the project with --swift-version or a .swift-version file.
solid answer
~40 sMany SwiftFormat rules emit syntax that only a given Swift release accepts: `conditionalAssignment` needs 5.9, `opaqueGenericParameters` and `genericExtensions` need 5.7, and `trailingCommas` only adds commas to multiline argument and parameter lists from 6.1. Without a version SwiftFormat skips those rewrites and warns "No Swift version was specified, so some formatting features were disabled"; worse, the default `--trailing-commas always` then *removes* trailing commas from argument and parameter lists. Set the version with `--swift-version` in `.swiftformat` or a `.swift-version` file holding the oldest compiler the project supports. A `.swift-version` file beats `--swift-version` on the command line, and both apply per directory. The Swift language mode is a separate setting, `--language-mode`.
code
swift · 18 linesfunc scheduleVisit(
petID: Int,
adopterName: String,
hour: Int,
) -> String {
"\(petID)-\(adopterName)-\(hour)"
}
let visit = scheduleVisit(
petID: 42,
adopterName: "Sam",
hour: 10,
)
let breeds = [
"beagle",
"poodle",
]go deeper
Recall that SwiftFormat needs to be told the project's Swift version, either with --swift-version or with a .swift-version file, and that it warns when it is missing.
Explain why version-gated rules stay off when the version is unset, which rules need 5.7, 5.9 or 6.1, and how the file and the option take precedence.
Set the minimum supported version rather than the newest, catch the trailing-comma flip-flop an unset version causes, and add --language-mode for Swift 6 mode targets.
Tie raising the declared Swift version to dropping the oldest supported Xcode, so formatter rewrites and toolchain support move in the same planned change.
## Why a formatter needs to know the Swift version SwiftFormat does more than move whitespace. Many of its rules rewrite code into a newer idiom, and that idiom only compiles on a compiler that understands it. SwiftFormat does not detect which toolchain will build the code, so it relies on you to say. Examples from the rule sources: - `conditionalAssignment` turns an assignment in every branch of an `if` or `switch` into an `if` or `switch` expression, which needs **Swift 5.9**. - `opaqueGenericParameters` rewrites a generic parameter into `some Protocol`, and `genericExtensions` rewrites `extension Array where Element == Foo` into `extension Array<Foo>`; both need **Swift 5.7**. - `trailingCommas` adds a trailing comma to multiline function calls and parameter lists only from **Swift 6.1**, the first release whose compiler accepts one there; multiline array and dictionary literals have always allowed it. ## What happens without a version With neither `--swift-version` nor a `.swift-version` file, SwiftFormat treats the version as undefined, which compares lower than any real release. It still formats, but: 1. Every rule or behaviour that needs a minimum Swift version is skipped, so the project silently misses those rewrites. 2. The run prints `warning: No Swift version was specified, so some formatting features were disabled.`, followed by advice to use `--swift-version` or a `.swift-version` file. 3. Rules that *remove* syntax unsupported by old compilers act on it. Under the default `--trailing-commas always`, a trailing comma after the last argument of a multiline call or the last parameter of a multiline declaration is removed, because a version below 6.1 is assumed not to accept it. Point 3 surprises teams: a developer on a Swift 6.1 toolchain adds trailing commas to a multiline call, and the next SwiftFormat run with no version strips them out again. ## Two ways to declare it, and which wins | Source | Where it lives | Notes | |---|---|---| | `--swift-version 6.1` | a line in `.swiftformat`, or a command-line argument | also accepted by the command plugin | | `.swift-version` file | a text file holding just the version, such as `6.1` | also read by some other tools | The precedence follows SwiftFormat's code and README: - A `.swift-version` file takes precedence over a `--swift-version` passed on the command line. - If the same directory has both a `.swiftformat` containing `--swift-version` and a `.swift-version` file, the `.swiftformat` line wins and SwiftFormat logs that it is ignoring the version file. - Both are applied hierarchically, so a module folder with its own `.swift-version` can declare a different version from the root. - A `.swift-version` inside an excluded directory is not read. ## Which version to write Write the **minimum** Swift version the project supports: the compiler in the oldest Xcode that CI or any teammate still builds with. Writing a newer version than that turns rewrites on that the oldest compiler rejects. A project that declares 6.1 while one CI lane still builds with a Swift 6.0 compiler will see SwiftFormat insert trailing commas into multiline calls, and that lane will fail to compile them. Raise the declared version deliberately, in the same change that drops the old Xcode, and expect a burst of rewrites in that commit as newly unlocked rules apply. ## The language mode is a separate setting A compiler version is not a language mode: the Swift 6 compiler can build a module in the Swift 5 or the Swift 6 language mode. SwiftFormat has `--language-mode` for this. If it is not set, SwiftFormat uses the default mode of the declared compiler version, which is the Swift 5 mode for both Swift 5.x and 6.x, so a module built in the Swift 6 mode should add `--language-mode 6`. Some rules behave differently between modes. How modes and compiler versions work in the compiler itself is covered with the Swift toolchain. ## A sensible setup - Commit a `.swift-version` file at the repository root, or a `--swift-version` line in the root `.swiftformat`, but keep one source of truth. - Add `--language-mode 6` when the targets build in Swift 6 mode. - Treat the warning about a missing version as a configuration bug in any CI log. - Check what applied: SwiftFormat logs "Reading swift-version file at ... (version 6.1)" or "Ignoring swift-version file at ..." for each file it meets. - Pass `--swift-version` to the command plugin or a build phase only when no file declares it, since a file closer to the sources overrides the argument.
- Should .swift-version name the Swift in the newest Xcode or the oldest one the team still builds with?The oldest. SwiftFormat's README describes the file as the minimum Swift version the project supports. A higher value lets rules such as `trailingCommas` or `conditionalAssignment` write syntax the oldest compiler rejects, so the build breaks on that toolchain only. Raise it in the change that drops the old Xcode.
- How does SwiftFormat's --language-mode differ from --swift-version?`--swift-version` is the compiler release, which decides what syntax is legal; `--language-mode` is the mode the code is compiled in, such as 5 or 6. SwiftFormat defaults the mode to Swift 5 for both 5.x and 6.x compilers, so a module compiled in the Swift 6 mode should say `--language-mode 6`, since some rules behave differently in it.
- SwiftFormat reads the Swift version from the active Xcode toolchain.
- A --swift-version on the command line overrides every .swift-version file.
- Declaring the newest Swift version is safest because it enables every rule.
- --swift-version changes which compiler or language mode builds the app.
- Without a Swift version, SwiftFormat refuses to run.
Assumes SwiftFormat 0.64.0; trailingCommas has handled Swift 6.1 argument and parameter lists since 0.56.0, and options have been spelled --swift-version and --language-mode since 0.57.0.