swift-format formats and diagnoses Swift source code according to a set of
style guidelines. It can be used as a command line tool
or linked into other applications as a Swift Package Manager dependency and
invoked via an API.
NOTE: No official Swift style guide has yet been proposed. The style that is currently enforced 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.
Command Line Usage
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-formatversion and exits.
-m/--mode <format|lint|dump-configuration>: The mode in which to run
formatmode formats source files. The
lintmode only prints diagnostics indicating style violations. The
dump-configurationmode dumps the default
swift-formatconfiguration 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.
The command line tool also provides some
hidden debugging options for use when developing
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.