swift-format provides the formatting technology for
SourceKit-LSP and the building
blocks for doing code formatting transformations.
NOTE: No default Swift code style guidelines have yet been proposed. The style that is currently applied by
swift-formatis just one possibility, and the code is provided so that it can be tested on real-world code and experiments can be made by modifying it.
swift-format depends on SwiftSyntax
and the standalone parsing library that is distributed as part of the Swift
toolchain. The SwiftSyntax version in use must match the toolchain version, so
you should check out and build
swift-format from the branch that is
compatible with the version of Swift you are using. This version dependency
is also expressed in the
SwiftSyntax dependency in
|Xcode Release||Swift Version||
|Xcode 12.0||Swift 5.3||
|Xcode 11.4||Swift 5.2||
|Xcode 11.0||Swift 5.1||
For example, if you are using Xcode 12.0 (Swift 5.3), you can check out and
swift-format using the following commands:
git clone -b swift-5.3-branch https://github.com/apple/swift-format.git cd swift-format swift build
You can also add the
--single-branch option if you only want to clone that
main branch is used for development and may depend on either a release
version of Swift or on a developer snapshot. Changes committed to
that are compatible with the latest release branch will be cherry-picked into
To test that the formatter was built succesfully and is compatible with your Swift toolchain, you can run the following command:
swift test --parallel
We recommend using the
--parallel flag to speed up the test run since there
are a large number of tests.
swift-format [OPTIONS] FILE...
swift-format tool can be invoked with one or more
.swift source files,
as well as the following command line options:
-v/--version: Prints the
swift-format version and exits.
-m/--mode <format|lint|dump-configuration>: The mode in which to run
format mode formats source files. The
only prints diagnostics indicating style violations. The
mode dumps the default
swift-format configuration to standard output.
If unspecified, the default mode is
--configuration <file>: The path to a JSON file that contains
configurable settings for
swift-format. If omitted, a
default configuration is use (which can be seen by running
-i/--in-place: Overwrites the input files when formatting instead of
printing the results to standard output.
-p/--parallel: Process files in parallel, simultaneously across
-r/--recursive: If specified, then the tool will process
files in any directories listed on the command line and their descendants.
Without this flag, it is an error to list a directory on the command line.
For any source file being checked or formatted,
swift-format looks for a
JSON-formatted file named
.swift-format in the same directory. If one is
found, then that file is loaded to determine the tool's configuration. If the
file is not found, then it looks in the parent directory, and so on.
If no configuration file is found, a default configuration is used. The
settings in the default configuration can be viewed by running
swift-format --mode dump-configuration, which will dump it to standard
--configuration <file> option is passed to
swift-format, then that
configuration will be used unconditionally and the file system will not be
See Documentation/Configuration.md for a description of the configuration file format and the settings that are available.
swift-format can be easily integrated into other tools written in Swift.
Instead of invoking the formatter by spawning a subprocess, users can depend on
swift-format as a Swift Package Manager dependency and import the
SwiftFormat module, which contains the entry points into the formatter's
diagnostic and correction behavior.
Formatting behavior is provided by the
SwiftFormatter class and linting
behavior is provided by the
SwiftLinter class. These APIs can be passed
either a Swift source file
URL or a
Syntax node representing a
SwiftSyntax syntax tree. The latter capability is particularly useful for
writing code generators, since it significantly reduces the amount of trivia
that the generator needs to be concerned about adding to the syntax nodes it
creates. Instead, it can pass the in-memory syntax tree to the
API and receive perfectly formatted code as output.
If you are interested in developing
swift-format, there is additional
documentation about that here.
|Last commit: 1 week ago|
This release is compatible with Swift 5.4.
Significant changes since the last release:
--parallelflag supports formatting multiple files in parallel. This should be much faster when formatting large numbers of files. (a062ec84d3230f9b9055123c7bb2903780c84608)
--ignore-unparsable-filesflag is now honored in
lintmode; unparsable files are silently ignored and no diagnostic is emitted. (fc3fab6bf6541e611830b122711af0bd750dec6f)
caseclauses inside a
switchstatement are formatted correctly. (8df2cb04f2aa41089cd14379552cb97bcc89133a)
UseLetInEveryBoundCaseVariableno longer produces incorrect diagnostics for certain patterns. (c3c17adbd93d9117f1d23fb05ffb7c435c23b581)
BeginDocumentationCommentWithOneLineSummaryhas been made opt-in by default. (22118db1668bb22af878d1ce31184533e419411b)
UseSynthesizedInitializernow produces more accurate diagnostics by considering the visibility of the stored properties in the type. (dd87cc2c9696ce8460265533471c75c225cde4fe)