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.
As of Swift 5.8, swift-format depends on the version of SwiftSyntax whose parser has been rewritten in Swift and no longer has dependencies on libraries in the Swift toolchain.
This change allows
swift-format to be built, developed, and run using
any version of Swift that can compile it, decoupling it from the version
that supported a particular syntax. However, earlier versions of swift-format
will still not be able to recognize new syntax added in later versions of the
language and parser.
Note also that the version numbering scheme has changed to match
SwiftSyntax; the 5.8 release of swift-format is
swift-format versions 0.50700.0 and earlier depend on versions of
SwiftSyntax that used a standalone
parsing library distributed as part of the Swift toolchain. When using these
versions, you should check out and build
swift-format from the release
tag or branch that is compatible with the version of Swift you are using.
The major and minor version components of
swift-format and SwiftSyntax must
be the same—this is expressed in the
SwiftSyntax dependency in
Package.swift—and those version components must match the
Swift toolchain that is installed and used to build and run the formatter:
|Xcode Release||Swift Version||
|Xcode 14.0||Swift 5.7||
|Xcode 13.3||Swift 5.6||
|Xcode 13.0–13.2||Swift 5.5||
|Xcode 12.5||Swift 5.4||
|Xcode 12.0–12.4||Swift 5.3||
|Xcode 11.4–11.7||Swift 5.2||
|Xcode 11.0–11.3||Swift 5.1||
For example, if you are using Xcode 13.3 (Swift 5.6), you will need
If you are mainly interested in using swift-format (rather than developing it), then you can get swift-format either via Homebrew or by checking out the source and building it.
brew install swift-format to install the latest version.
Install swift-fromat using the following commands:
VERSION=509.0.0 # replace this with the version you need git clone https://github.com/apple/swift-format.git cd swift-format git checkout "tags/$VERSION" swift build -c release
Note that the
git checkout command above will leave the repository in a
"detached HEAD" state. This is fine if building and running the tool is all you
want to do.
Once the build has finished, the
swift-format executable will be located at
To test that the formatter was built successfully and is compatible with your Swift toolchain, you can also 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.
The general invocation syntax for
swift-format is as follows:
swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]
The tool supports a number of subcommands, each of which has its own options
and are described below. Descriptions of the subcommands that are available
can also be obtained by running
swift-format --help, and the description of
a specific subcommand can be obtained by using the
--help flag after the
subcommand name; for example,
swift-format lint --help.
swift-format [format] [OPTIONS...] [FILES...]
format subcommand formats one or more Swift source files (or source code
from standard input if no file paths are given on the command line). Writing
format subcommand is optional; it is the default behavior if no other
subcommand is given.
This subcommand supports all of the common lint and format options, as well as the formatting-only options below:
-i/--in-place: Overwrites the input files when formatting instead of printing the results to standard output. No backup of the original file is made before it is overwritten.
swift-format lint [OPTIONS...] [FILES...]
lint subcommand checks one or more Swift source files (or source code
from standard input if no file paths are given on the command line) for style
violations and prints diagnostics to standard error for any violations that
This subcommand supports all of the common lint and format options, as well as the linting-only options below:
-s/--strict: If this option is specified, lint warnings will cause the tool to exit with a non-zero exit code (failure). By default, lint warnings do not prevent a successful exit; only fatal errors (for example, trying to lint a file that does not exist) cause the tool to exit unsuccessfully.
The following options are supported by both the
--assume-filename <path>: The file path that should be used in
diagnostics when linting or formatting from standard input. If this option
is not provided, then
<stdin> will be used as the filename printed in
--color-diagnostics/--no-color-diagnostics: By default,
will print diagnostics in color if standard error is connected to a
terminal and without color otherwise (for example, if standard error is
being redirected to a file). These flags can be used to force colors on
or off respectively, regardless of whether the output is going to a
--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
--ignore-unparsable-files: If this option is specified and a source file
contains syntax errors or can otherwise not be parsed successfully by the
Swift syntax parser, it will be ignored (no diagnostics will be emitted
and it will not be formatted). Without this option, an error will be
emitted for any unparsable files.
-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.
dump-configuration subcommand dumps the default configuration in JSON
format to standard output. This can be used to simplify generating a custom
configuration, by redirecting it to a file and editing it.
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 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 -v or
swift-format --version will print version
swift-format version and then exit.
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.
main branch is used for development. Pull requests should be created
to merge into the
main branch; changes that are low-risk and compatible with
the latest release branch may be cherry-picked into that branch after they have
been merged into
If you are interested in developing
swift-format, there is additional
documentation about that here.
|Last commit: 9 hours ago|
This release is compatible with Swift 5.9.
Significant changes since the last release:
AlwaysUseLiteralForEmptyCollectionInit: transforms no-argument initializer calls on collection types to use the empty collection literal instead. For example,
let x = [Int]()will be transformed into
let x: [Int] = . This rule is opt-in (disabled by default).
NoPlaygroundLiterals: emits lint findings when the playground literals (
#imageLiteral) are used in code. Enabled by default.
OmitExplicitReturns: removes unnecessary
returnkeywords from single-expression function/closure/subscript/accessor bodies. This rule is opt-in (disabled by default).
ReplaceForEachWithForLoop: emits lint findings when the
forEachmethod is called with a closure literal at the end of a member access chain, indicating that it should be replaced by a
forloop instead. Enabled by default.
TypeNamesShouldBeCapitalized: emits lint findings when a type is declared with a name that is not
UpperCamelCase. Enabled by default.
multiElementCollectionTrailingCommas(boolean): When set to
false, the last element of a multi-element array or dictionary literal will not have a trailing comma, even when the literal wraps across multiple lines. Defaults to
true(preserving the behavior of previous releases).
caseblock that contains no statements.
inkeyword and the first statement.
importstatements are no longer wrapped.
NoParensAroundConditionsrule no longer removes parentheses around an immediately called closure.
NoAssignmentInExpressionsrule can be configured to ignore assignments that occur inside certain function calls. The default configuration ignores assignments inside
#ifexpressions are no longer indented too far when they follow a closing parenthesis.
UseShorthandTypeNamesrule properly parenthesizes optional
some/anytypes; for example,
(any P)?, not
any P?(which is invalid).
UseSynthesizedInitializerrule no longer warns that an initializer is redundant if it is declared with any attributes.
--targetargument is not specified.
For developers using swift-format as a library, the types in the
SwiftFormatConfiguration module have been folded into the
SwiftFormat module. The
SwiftFormat module is now the sole module you should import to use the linter/formatter APIs.
SwiftFormatConfiguration module still exists to re-export the types for backwards compatibility, but this will be removed in the 510.0.0 release.