Every swift-format Option, and What It Actually Changes

lineLength#

The maximum number of characters on a line. Exceeding it triggers the line-breaking strategy.

1
// lineLength: 80
2
let view = makeRow(title: "Title", subtitle: "Subtitle", icon: iconName, action: handler)
3
let view = makeRow(
4
  title: "Title", subtitle: "Subtitle", icon: iconName, action: handler)

My choice: 100 (the default). Swift type names and argument labels are long to begin with, and 80 shreds SwiftUI view code. 100 is the value in the Google Swift Style Guide and swift-format’s own default.

indentation#

What one level of indentation is made of. Either {"spaces": N} or {"tabs": N}.

1
struct Point {
2
  var x: Int
3
  func move() {
4
    x += 1
5
  }
6
    var x: Int
7
    func move() {
8
        x += 1
9
    }
10
}

My choice: {"spaces": 4}. swift-format defaults to 2, but Xcode’s default editor setting is 4, and Apple’s own sample code uses 4. I don’t want the indentation I type by hand in Xcode to disagree with the indentation I get after formatting.

tabWidth#

This name is misleading. It is not “indent width” — it is how many columns one tab character counts as when measuring line length.

If indentation uses spaces, this value has no effect on output at all. It only matters with tab indentation. The two snippets below are the same code, the same lineLength: 60, the same tab indentation, differing only in tabWidth:

1
// tabWidth: 8 — two levels of tabs count as 16 columns, leaving too little room, so it wraps
2
func outer() {
3
  func inner() {
4
    let r = compute(
5
      alpha: 1, beta: 2, gamma: 3,
6
      delta: 44)
7
  }
8
}
9

10
// tabWidth: 4 — two levels count as 8 columns, and the call fits on one line
11
func outer() {
12
  func inner() {
13
    let r = compute(alpha: 1, beta: 2, gamma: 3, delta: 44)
14
  }
15
}

My choice: 4, though honestly this key does nothing in my configuration. I indent with spaces, so swift-format never encounters a tab whose width it needs to convert. I keep it only so it matches my editor setting; removing it would change nothing.

indentBlankLines#

Whether blank lines get the current level of indentation added to them (that is, a run of trailing spaces).

1
func f() {
2
    let a = 1
3

4
    ⎵⎵⎵⎵
5
    let b = 2
6
}

(The ⎵ marks are the actual spaces produced.)

My choice: false (the default). Turning it on manufactures trailing whitespace, which fights both the “strip trailing spaces on save” setting in most editors and the way git diffs are read.

maximumBlankLines#

How many consecutive blank lines are allowed; anything more is collapsed.

1
let a = 1
2

3

4
let b = 2

(That is the effect of going from 2 back to the default 1.)

My choice: 1 (the default). I use blank lines to separate logical blocks, but I don’t need two or more of them to express a “bigger” separation — that is what a heading comment is for.

spacesBeforeEndOfLineComments#

How many spaces sit before an end-of-line // comment.

1
let a = 1  // one
2
let bb = 22  // two
3
let a = 1 // one
4
let bb = 22 // two

(That is the effect of setting it to 1.) Note that it does not align anything; it only guarantees a fixed number of spaces.

My choice: 2 (the default). With one space, the comment sits too close to the code; two spaces separate them visually.

spacesAroundRangeFormationOperators#

Whether ... and ..< get spaces around them.

1
let r = 0..<10
2
let c = 1...5
3
let r = 0 ..< 10
4
let c = 1 ... 5

My choice: false (the default). I read 0..<10 as a single unit; adding spaces makes it look like three separate words.

indentConditionalCompilationBlocks#

Whether the body of an #if / #endif block is indented one more level.

1
func f() {
2
  #if DEBUG
3
  let a = 1
4
  print(a)
5
    let a = 1
6
    print(a)
7
  #endif
8
}

(The default, true, produces the right-hand side.)

My choice: true (the default). #if is a structure with an opening and a closing, so indenting its contents matches intuition.

indentSwitchCaseLabels#

Whether case is indented relative to switch.

1
switch v {
2
case 1:
3
  print(1)
4
default:
5
  break
6
  case 1:
7
    print(1)
8
  default:
9
    break
10
}

My choice: false (the default). This is how the Swift community writes it and how Apple’s documentation lays it out. Turning it on pushes the entire switch two levels to the right, which is expensive in already-nested code.

respectsExistingLineBreaks#

Whether the line breaks you wrote by hand are honored.

1
let a = compute(
2
  x: 1,
3
  y: 2
4
)
5
let a = compute(x: 1, y: 2)
6
let b = 1 + 2

(That is the effect of setting it to false: anything that can be joined is joined.)

My choice: true (the default). I think this is the most important key in the file. Turn it off and swift-format becomes a line-density maximizer: an argument list you split by hand to express grouping gets mercilessly rejoined. Leave it on and your line breaks survive as long as they don’t violate a rule — the formatter enforces a floor, and you handle expression.

lineBreakBeforeEachArgument#

When an argument list doesn’t fit on one line: pack each line as full as possible, or give every argument its own line.

1
let view = makeRow(
2
  title: "Title", subtitle: "Subtitle", icon: iconName, action: handler, isEnabled: true)
3
  title: "Title",
4
  subtitle: "Subtitle",
5
  icon: iconName,
6
  action: handler,
7
  isEnabled: true
8
)

Function declarations behave the same way:

1
func makeRow(
2
  title: String, subtitle: String, iconName: String, action: @escaping () -> Void, isEnabled: Bool,
3
  title: String,
4
  subtitle: String,
5
  iconName: String,
6
  action: @escaping () -> Void,
7
  isEnabled: Bool,
8
  badgeCount: Int
9
) -> Row {

My choice: true. The default packing has a practical problem: adding one argument reflows every argument after it, so the diff looks like five changed lines when you only added one. With one argument per line, adding an argument adds a line. SwiftUI initializers have many long parameters, and the difference is visible in code review.

The cost is more vertical lines. I’ll take it.

lineBreakBeforeEachGenericRequirement#

The same idea, applied to where clauses.

1
func merge<A, B>(_ a: A, _ b: B) -> [A.Element]
2
where
3
  A: Sequence, B: Sequence, A.Element == B.Element, A.Element: Hashable, B.Element: Comparable,
4
  A: Codable, B: Codable, A: Sendable
5
  A: Sequence,
6
  B: Sequence,
7
  A.Element == B.Element,
8
  A.Element: Hashable,
9
  B.Element: Comparable,
10
  A: Codable,
11
  B: Codable,
12
  A: Sendable
13
{

Note that it only kicks in when the where clause is long enough to need wrapping; short ones are untouched.

My choice: true. Same reasoning as the previous key, kept consistent. In practice my project has no where clause long enough to wrap yet, so for now this one is written for the future.

lineBreakBeforeControlFlowKeywords#

Whether keywords like else and catch start a new line.

1
  if condition {
2
    print(a)
3
  } else {
4
  }
5
  else {
6
    print(0)
7
  }
8
}

My choice: false (the default). } else { is the universal Swift spelling; switching to Allman style would make the code look out of place in any Swift project.

lineBreakBetweenDeclarationAttributes#

Whether multiple attributes each get their own line.

1
@MainActor @preconcurrency final class Store {
2
@MainActor
3
@preconcurrency
4
final class Store {
5
  var value = 0
6
}

My choice: false (the default). Combinations like @State private var are everywhere in SwiftUI, and forcing a break turns the property section into a vertical stripe. The option is also global — there is no way to apply it only to long attributes.

lineBreakAroundMultilineExpressionChainComponents#

When a method chain doesn’t fit: break between method names, or break inside the argument parentheses.

1
let names = people.filter { $0.age > 18 }.map { $0.name.uppercased() }.sorted().joined(
2
  separator: ", ")
3
let names = people.filter { $0.age > 18 }.map { $0.name.uppercased() }.sorted()
4
  .joined(separator: ", ")

My choice: false (the default). I went back and forth on this one. Turning it on gives semantically better break points (at the .), but its actual behavior is “force a break before and after every component of a multiline chain” — once a chain is judged multiline, the whole thing fans out. The default output is good enough in my code, so I left it alone.

prioritizeKeepingFunctionOutputTogether#

When a function signature doesn’t fit, which part gets protected. This is my favorite key in the file.

1
func loadConfiguration(from url: URL, using decoder: JSONDecoder, strict: Bool) throws
2
  -> Configuration
3
{
4
func loadConfiguration(
5
  from url: URL, using decoder: JSONDecoder, strict: Bool
6
) throws -> Configuration {
7
  try decoder.decode(Configuration.self, from: Data(contentsOf: url))
8
}

The default (false) throws the return type onto the next line, and because the signature now spans lines, the opening brace is forced onto a line of its own — three lines of signature plus a lonely {. Turned on, the parameter list gets split instead, and ) throws -> Configuration { stays together.

My choice: true. The return type is one of the most informative parts of a signature, and there is no reason to cut it away from the parameter list. The orphaned { is also unusually conspicuous in code indented with 4 spaces.

multiElementCollectionTrailingCommas#

Whether a multi-element array or dictionary literal gets a comma after its last element.

1
let colors = [
2
  "red",
3
  "green",
4
  "blue"
5
  "blue",
6
]

Single-element collections are unaffected — ["only"] split across lines gets no comma.

My choice: true (the default), but it no longer does anything in my configuration. See the next key for why.

multilineTrailingCommaBehavior#

A wider scope: argument lists, tuples, every “symmetrically delimited comma-separated list”, including collection literals. Three values:

• keptAsWritten (default): keep what you wrote, add nothing, and leave collection literals to the previous key
• alwaysUsed: add one to every multiline list
• neverUsed: remove them all

1
let view = makeRow(
2
  title: "Title",
3
  subtitle: "Subtitle",
4
  icon: iconName,
5
  icon: iconName
6
)

My choice: neverUsed.

I originally set alwaysUsed. The reasoning was that a trailing comma makes the last element as easy to add, remove, or reorder as any other, so adding an argument touches one line of diff. That reasoning is sound, but it has a gap: as the name says, multilineTrailingCommaBehavior only governs multiline lists. A single-line makeRow(title: "a", subtitle: "b") will never have a comma added.

So what alwaysUsed actually produces is a split rule — commas on multiline lists, none on single-line ones. The same call switches style depending on whether it crosses 100 columns. neverUsed is one rule for every case: no trailing commas anywhere. I switched.

The cost is giving up that small diff benefit. What I get back is never having to think about whether a given list is currently single-line or multiline.

Two knock-on effects.

First, neverUsed overrides multiElementCollectionTrailingCommas. Even with that key still set to true, trailing commas in collection literals are removed:

1
// multiElementCollectionTrailingCommas: true + multilineTrailingCommaBehavior: neverUsed
2
let colors = [
3
    "red",
4
    "green",
5
    "blue"
6
]

In other words, the multiElementCollectionTrailingCommas line in my configuration is now inert. I keep it so that switching back to keptAsWritten later requires no thinking, but it genuinely affects no output.

Second, the compiler requirement disappears. Trailing commas in argument lists are syntax introduced by SE-0439 and require a Swift 6.1 or newer compiler (I tested this: it is not gated by language mode — -swift-version 5 compiles fine as long as the compiler is new enough). Choosing alwaysUsed means producing code that older toolchains can’t build; neverUsed sidesteps the question.

A bug, incidentally. A hand-written single-line trailing comma is legal syntax (makeRow(title: "a", subtitle: "b",) and [1, 2, 3,] both compile), but swift-format doesn’t clean up after itself. neverUsed removes the comma and leaves a space behind; it takes a second pass to converge:

1
// input
2
let v = makeRow(title: "a", subtitle: "b",)
3

4
// first pass
5
let v = makeRow(title: "a", subtitle: "b" )
6

7
// second pass
8
let v = makeRow(title: "a", subtitle: "b")

The default keptAsWritten is worse: it preserves ("b", ) exactly, no matter how many times you run it. Collection literals don’t have this problem. You are unlikely to type a single-line trailing comma yourself, but if you are migrating code in from another project, it is worth running the formatter twice before committing.

reflowMultilineStringLiterals#

Whether overlong lines inside a multiline string literal are rewrapped using \ continuations.

1
// never (default)
2
let message = """
3
  This line is short.
4
  This particular line is quite long and definitely goes past the configured maximum line length limit of one hundred columns.
5
  """
6

7
// onlyLinesOverLength
8
let message = """
9
  This line is short.
10
  This particular line is quite long and definitely goes past the configured maximum line length \
11
  limit of one hundred columns.
12
  """

The third value, always, is documented as “always reflow, ignoring existing escaped newlines”. In the cases I tried it produced output identical to onlyLinesOverLength — it does not join short lines together. The difference presumably only shows up in literals that already contain \ continuations.

My choice: onlyLinesOverLength. I don’t want string literals to be the one place that can break past 100 columns (that would make lineLength decorative), but I also don’t want the formatter touching short text I laid out line by line. This middle value is exactly right.

fileScopedDeclarationPrivacy#

Whether file-scoped private declarations use private or fileprivate. Backs the FileScopedDeclarationPrivacy rule.

1
fileprivate let cache = 1
2
fileprivate func helper() {}
3
private let cache = 1
4
private func helper() {}

At file scope the two keywords mean exactly the same thing, so this is purely about consistency.

My choice: private (the default). Shorter, and visually consistent with private inside a type.

noAssignmentInExpressions#

The allowlist for the NoAssignmentInExpressions rule: which functions may contain an assignment in their arguments.

The default is ["XCTAssertNoThrow"], because XCTAssertNoThrow(x = try compute()) is a common pattern in tests. Empty the allowlist and that line gets reported:

1
warning: [NoAssignmentInExpressions] move this assignment expression into its own statement

My choice: keep the default ["XCTAssertNoThrow"]. My project uses Swift Testing rather than XCTest, so the allowlist is currently idling. Leaving the default costs nothing.

orderedImports#

Two switches for the OrderedImports rule.

shouldGroupImports (default true): group different kinds of import, separated by a blank line.

1
import Foundation
2
import UIKit
3

4
import enum Swift.Optional
5

6
@testable import MyApp
7
import UIKit

The order is: plain imports → single-symbol imports (import enum Swift.Optional) → @testable imports, alphabetized within each group. Turn it off and everything is merged into one alphabetized list.

includeConditionalImports (default false): whether imports inside #if blocks are sorted too.

1
#if canImport(Combine)
2
  import Combine
3
  import Accelerate
4
  import Combine
5
#endif

My choice: both at their defaults (grouping = true, conditional = false). Grouping makes @testable visible at a glance. The order of imports inside a conditional block is sometimes meaningful (dependencies, for instance), and I’d rather the tool left it alone.

AlwaysUseLiteralForEmptyCollectionInit (rewrites)#

1
var names = [String]()
2
var lookup = [String: Int]()
3
var names: [String] = []
4
var lookup: [String: Int] = [:]

Why: The two spellings are equivalent, but the second puts the type where types go. Annotation on the left of the declaration, value on the right — the same shape as var x: Int = 0.

BeginDocumentationCommentWithOneLineSummary (reports only)#

Requires the first sentence of a doc comment to stand alone as a one-line summary.

1
/// Returns the sum of two integers. This function is very simple. It adds them.
2
func add(_ a: Int, _ b: Int) -> Int { a + b }

1
warning: [BeginDocumentationCommentWithOneLineSummary]
2
add a blank comment line after this sentence: "Returns the sum of two integers."

Why: Xcode’s Quick Help and DocC both take only the first paragraph as the summary. Write a three-sentence summary and you get a wall of text in Quick Help.

NeverForceUnwrap / NeverUseForceTry / NeverUseImplicitlyUnwrappedOptionals (all report only)#

1
warning: [NeverForceUnwrap] do not force unwrap 'Int(s!)'
2
warning: [NeverUseForceTry] do not use force try
3
warning: [NeverUseImplicitlyUnwrappedOptionals] use 'String' or 'String?' instead of 'String!'

Why: Atofolio is an archive app that imports external data — fields from Bangumi, Steam, and Apple Music can go missing or change shape at any time. The project’s first principle is that missing information is never invented, and unknown stays unknown. ! is the syntax that conflicts with that principle most directly: it converts “there may be no value here” into “crash if there is no value here”.

These three only report under lint; they never rewrite code — and they shouldn’t, because the correct fix (guard let, do/catch, changing the type) depends on context.

The cost is a certain number of unavoidable reports. UIKit’s @IBOutlet is implicitly unwrapped by design, and calls like Bundle.main.url(forResource:), where the resource is certainly inside the app bundle, are hard to write without !. For those, a one-line comment grants a local exemption:

1
// swift-format-ignore: NeverUseImplicitlyUnwrappedOptionals
2
var label: String!

The directive applies only to the declaration immediately following it; later declarations are checked as usual. To exempt an entire file, use // swift-format-ignore-file.

NoEmptyLinesOpeningClosingBraces (rewrites)#

1
struct S {
2

3
  var x = 1
4

5
}

Why: A blank line pressed against a brace expresses no grouping. It is just a leftover keystroke.

OmitExplicitReturns (rewrites)#

1
func double(_ x: Int) -> Int {
2
  return x * 2
3
  x * 2
4
}
5
var squared: Int {
6
  return 4
7
  4
8
}

Why: SwiftUI’s body and a great many computed properties are single expressions. Since the language already allows omitting return, let the tool omit it uniformly rather than leaving it to each person’s habit. Together with the default rule UseSingleLinePropertyGetter below (which strips the redundant get { }), a computed property simplifies all the way down to the expression itself.

I hold some doubt about this one: without return, single-expression functions and closures are harder to tell apart visually. But in SwiftUI code the payoff is larger.

UseEarlyExits (rewrites)#

1
func f(_ x: Int?) {
2
  if let x = x {
3
    print(x)
4
  } else {
5
  guard let x = x else {
6
    return
7
  }
8
  print(x)
9
  print("done")
10
}

Why: guard puts “leave if the condition fails” up front and keeps the main logic at the outermost indentation. This is one of the rare semantic-level rewrites a tool can perform reliably in Swift.

Note that it only handles the case where the else branch contains a single exit statement; it won’t meddle with complex branches.

UseWhereClausesInForLoops (rewrites)#

1
func f(_ xs: [Int]) {
2
  for x in xs {
3
    if x > 0 {
4
      print(x)
5
    }
6
  for x in xs where x > 0 {
7
    print(x)
8
  }
9
}

Why: One less level of indentation, and where separates filtering from processing at the syntax level.

ValidateDocumentationComments (reports only)#

Checks that a doc comment’s parameter list matches the actual signature.

1
/// Returns the sum.
2
///
3
/// - Parameters:
4
///   - a: first
5
///   - c: wrong name
6
/// - Returns: the sum
7
func add(a: Int, b: Int) -> Int { a + b }

1
warning: [ValidateDocumentationComments]
2
change the parameters of the documentation of 'add' to match its parameters

Why: A doc comment out of sync with its signature is one of the hardest classes of error to notice, because it affects neither compilation nor runtime. It only misleads the next person reading the code, which is usually me.

Rewriting rules#

DoNotUseSemicolons — semicolons become line breaks.

1
let a = 1; let b = 2;
2
let a = 1
3
let b = 2

FullyIndirectEnum — when every case is indirect, hoist it to the enum.

1
enum Tree {
2
  indirect case node(Tree, Tree)
3
  indirect case leaf(Tree)
4
indirect enum Tree {
5
  case node(Tree, Tree)
6
  case leaf(Tree)
7
}

GroupNumericLiterals — underscore grouping in long numeric literals.

1
let big = 1000000
2
let hex = 0xFFFFFFFF
3
let big = 1_000_000
4
let hex = 0xFFFF_FFFF
5
let bin = 0b11110000

Note the last line is untouched: an 8-bit binary literal is under the threshold.

NoAccessLevelOnExtensionDeclaration — move the access level from the extension to its members.

1
public extension String {
2
  func shout() -> String { uppercased() }
3
extension String {
4
  public func shout() -> String { uppercased() }
5
}

NoAssignmentInExpressions — split an assignment out of an expression into its own statement.

1
func f() -> Int {
2
  var x = 0
3
  return x = 5
4
  x = 5
5
  return
6
}

(The original code in this example was already suspicious, and the rewritten version won’t necessarily compile. The value of the rule is that it forces you to look at that line.)

NoCasesWithOnlyFallthrough — merge cases that only fall through.

1
case 1:
2
  fallthrough
3
case 2:
4
case 1, 2:
5
  print("small")

NoEmptyTrailingClosureParentheses — empty parentheses before a trailing closure.

1
UIView.animate() {
2
UIView.animate {

NoLabelsInCasePatterns — redundant labels in case patterns.

1
case .a(x: let x, y: let y):
2
case .a(let x, let y):

NoParensAroundConditions — parentheses around conditions.

1
if (x > 0) {
2
if x > 0 {
3
while (x < 10) { break }
4
while x < 10 { break }

NoVoidReturnOnFunctionSignature — an explicit -> Void on a function signature.

1
func f() -> Void {}
2
func g() -> () {}
3
func f() {}
4
func g() {}

ReturnVoidInsteadOfEmptyTuple — () becomes Void in closure types.

1
let handler: (Int) -> () = { _ in }
2
let handler: (Int) -> Void = { _ in }

The opposite direction from the previous rule, but not a contradiction: on a function signature the return type is deleted outright, while in a type annotation it is spelled Void.

OneCasePerLine — cases with associated or raw values get their own line.

1
enum E {
2
  case a, b, c(Int)
3
  case d = 1, e = 2
4
  case a, b
5
  case c(Int)
6
  case d = 1
7
  case e = 2
8
}

Note that the valueless case a, b is kept on one line.

OneVariableDeclarationPerLine — one variable per line.

1
let a = 1, b = 2, c = 3
2
let a = 1
3
let b = 2
4
let c = 3

UseExplicitNilCheckInConditions — if let _, which discards the bound value, becomes a nil comparison.

1
if let _ = x {
2
if x != nil {

UseLetInEveryBoundCaseVariable — case let .a(x, y) becomes a let on each binding.

1
case let .a(x, y):
2
case .a(let x, let y):

UseShorthandTypeNames — generic spellings become shorthand.

1
var a: Array<Int> = []
2
var b: Optional<String> = nil
3
var c: Dictionary<String, Int> = [:]
4
var a: [Int] = []
5
var b: String? = nil
6
var c: [String: Int] = [:]

UseSingleLinePropertyGetter — the redundant get { } in a read-only property.

1
var x: Int {
2
  get {
3
    return 1
4
  }
5
  return 1
6
}

UseTripleSlashForDocumentationComments — block-comment docs become ///.

1
/**
2
 * A documented function.
3
 */
4
/// A documented function.
5
func f() {}

FileScopedDeclarationPrivacy and OrderedImports were covered earlier, since each has its own configuration key.

Reporting rules#

These never change code; they only report under lint.

I have no strong opinions about this group; everything they report is a real problem. The one worth a note is ReplaceForEachWithForLoop: you can’t use break or continue inside forEach, and return doesn’t mean what it looks like (it exits only that one closure call), so for-in really is safer.