Repository files navigation

swift-format provides the formatting technology forSourceKit-LSP and the buildingblocks for doing code formatting transformations.

This package can be used as acommand line toolor linked into other applications as a Swift Package Manager dependency andinvoked via anAPI.

NOTE: No default Swift code style guidelines have yet been proposed. Thestyle that is currently applied byswift-format is just one possibility,and the code is provided so that it can be tested on real-world code andexperiments can be made by modifying it.

As of Swift 5.8, swift-format depends on the version ofSwiftSyntax whose parser has beenrewritten in Swift and no longer has dependencies on libraries in theSwift toolchain.

This change allowsswift-format to be built, developed, and run usingany version of Swift that can compile it, decoupling it from the versionthat supported a particular syntax. However, earlier versions of swift-formatwill still not be able to recognize new syntax added in later versions of thelanguage and parser.

Note also that the version numbering scheme has changed to matchSwiftSyntax; the 5.8 release of swift-format is508.0.0, not0.50800.0.

swift-format versions 0.50700.0 and earlier depend on versions ofSwiftSyntax that used a standaloneparsing library distributed as part of the Swift toolchain. When using theseversions, you should check out and buildswift-format from the releasetag or branch that is compatible with the version of Swift you are using.

The major and minor version components ofswift-format and SwiftSyntax mustbe the same—this is expressed in theSwiftSyntax dependency inPackage.swift—and those version components must match theSwift toolchain that is installed and used to build and run the formatter:

For example, if you are using Xcode 13.3 (Swift 5.6), you will needswift-format 0.50600.0.

If you are mainly interested in using swift-format (rather than developing it),then you can get swift-format either viaHomebrew or by checking out thesource and building it.

Runbrew install swift-format to install the latest version.

Installswift-format using the following commands:

VERSION=510.1.0# replace this with the version you needgit clone https://github.com/apple/swift-format.gitcd swift-formatgit checkout"tags/$VERSION"swift build -c release

Note that thegit checkout command above will leave the repository in a"detached HEAD" state. This is fine if building and running the tool is all youwant to do.

Once the build has finished, theswift-format executable will be located at.build/release/swift-format.

To test that the formatter was built successfully and is compatible with yourSwift toolchain, you can also run the following command:

swifttest --parallel

We recommend using the--parallel flag to speed up the test run since thereare a large number of tests.

The general invocation syntax forswift-format is as follows:

swift-format [SUBCOMMAND] [OPTIONS...] [FILES...]

The tool supports a number of subcommands, each of which has its own optionsand are described below. Descriptions of the subcommands that are availablecan also be obtained by runningswift-format --help, and the description ofa specific subcommand can be obtained by using the--help flag after thesubcommand name; for example,swift-format lint --help.

swift-format [format] [OPTIONS...] [FILES...]

Theformat subcommand formats one or more Swift source files (or source codefrom standard input if no file paths are given on the command line). Writingout theformat subcommand is optional; it is the default behavior if no othersubcommand is given.

This subcommand supports all of thecommon lint and format options,as well as the formatting-only options below:

• -i/--in-place: Overwrites the input files when formatting instead ofprinting the results to standard output.No backup of the original file ismade before it is overwritten.

swift-format lint [OPTIONS...] [FILES...]

Thelint subcommand checks one or more Swift source files (or source codefrom standard input if no file paths are given on the command line) for styleviolations and prints diagnostics to standard error for any violations thatare detected.

This subcommand supports all of thecommon lint and format options,as well as the linting-only options below:

• -s/--strict: If this option is specified, lint warnings will cause thetool to exit with a non-zero exit code (failure). By default, lint warningsdo not prevent a successful exit; only fatal errors (for example, trying tolint a file that does not exist) cause the tool to exit unsuccessfully.

The following options are supported by both theformat andlintsubcommands:

• --assume-filename <path>: The file path that should be used indiagnostics when linting or formatting from standard input. If this optionis not provided, then<stdin> will be used as the filename printed indiagnostics.

• --color-diagnostics/--no-color-diagnostics: By default,swift-formatwill print diagnostics in color if standard error is connected to aterminal and without color otherwise (for example, if standard error isbeing redirected to a file). These flags can be used to force colors onor off respectively, regardless of whether the output is going to aterminal.

• --configuration <file>: The path to a JSON file that containsconfigurable settings forswift-format. If omitted, a default configuration is use (whichcan be seen by runningswift-format dump-configuration).

• --ignore-unparsable-files: If this option is specified and a source filecontains syntax errors or can otherwise not be parsed successfully by theSwift syntax parser, it will be ignored (no diagnostics will be emittedand it will not be formatted). Without this option, an error will beemitted for any unparsable files.

• -p/--parallel: Process files in parallel, simultaneously acrossmultiple cores.

• -r/--recursive: If specified, then the tool will process.swift sourcefiles 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.

swift-format dump-configuration

Thedump-configuration subcommand dumps the default configuration in JSONformat to standard output. This can be used to simplify generating a customconfiguration, by redirecting it to a file and editing it.

For any source file being checked or formatted,swift-format looks for aJSON-formatted file named.swift-format in the same directory. If one isfound, then that file is loaded to determine the tool's configuration. If thefile is not found, then it looks in the parent directory, and so on.

If no configuration file is found, a default configuration is used. Thesettings in the default configuration can be viewed by runningswift-format dump-configuration, which will dump it to standardoutput.

If the--configuration <file> option is passed toswift-format, then thatconfiguration will be used unconditionally and the file system will not besearched.

SeeDocumentation/Configuration.md for adescription of the configuration file format and the settings that areavailable.

Runningswift-format -v orswift-format --version will print versioninformation aboutswift-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 onswift-format as a Swift Package Manager dependency and import theSwiftFormat module, which contains the entry points into the formatter'sdiagnostic and correction behavior.

Formatting behavior is provided by theSwiftFormatter class and lintingbehavior is provided by theSwiftLinter class. These APIs can be passedeither a Swift source fileURL or aSyntax node representing aSwiftSyntax syntax tree. The latter capability is particularly useful forwriting code generators, since it significantly reduces the amount of triviathat the generator needs to be concerned about adding to the syntax nodes itcreates. Instead, it can pass the in-memory syntax tree to theSwiftFormatAPI and receive perfectly formatted code as output.

Please see the documentation in theSwiftFormatter andSwiftLinter classes for moreinformation about their usage.

Themain branch is used for development. Pull requests should be createdto merge into themain branch; changes that are low-risk and compatible withthe latest release branch may be cherry-picked into that branch after they havebeen merged intomain.

If you are interested in developingswift-format, there is additionaldocumentation about thathere.