Convert Figma logo to code with AI

swiftlang logoswift-format

Formatting technology for Swift source code

2,449
223
2,449
93
View on GitHub

Top Related Projects

swiftlang's avatar

swift-syntax

3,187

A set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.

realm's avatar

SwiftLint

18,578

A tool to enforce Swift style and conventions.

nicklockwood's avatar

SwiftFormat

7,807

A command-line tool and Xcode Extension for formatting Swift code

swiftlang's avatar

swift-evolution

15,342

This maintains proposals for changes and user-visible enhancements to the Swift Programming Language.

apple's avatar

swift-argument-parser

3,308

Straightforward, type-safe argument parsing for Swift

swiftlang's avatar

swift-package-manager

9,727

The Package Manager for the Swift Programming Language

Quick Overview

Swift-format is an official tool developed by the Swift project to automatically format Swift source code. It aims to enforce a consistent style across Swift codebases, improving readability and reducing the need for manual formatting during code reviews.

Pros

  • Official tool backed by the Swift project, ensuring compatibility and ongoing support
  • Highly configurable, allowing teams to customize formatting rules to match their preferences
  • Integrates well with popular IDEs and text editors
  • Can be used as a command-line tool or as a library in Swift projects

Cons

  • Some developers may find the default formatting rules too opinionated
  • Can occasionally produce unexpected results in complex code structures
  • May require initial setup and configuration to match team preferences
  • Performance can be slower on very large codebases

Code Examples

  1. Basic usage as a command-line tool:
swift-format format --in-place MyFile.swift

This command formats the MyFile.swift file in-place.

  1. Using swift-format as a library in a Swift project:
import SwiftFormat

let formatter = SwiftFormatter(configuration: .default)
let formattedCode = try formatter.format(source: "let x=5", assumingFileURL: nil)
print(formattedCode)

This example demonstrates how to use swift-format as a library to format a simple Swift code snippet.

  1. Customizing formatting rules:
import SwiftFormat

var configuration = Configuration()
configuration.indentation = .spaces(4)
configuration.lineLength = 100

let formatter = SwiftFormatter(configuration: configuration)
let formattedCode = try formatter.format(source: sourceCode, assumingFileURL: nil)

This example shows how to create a custom configuration and use it with the formatter.

Getting Started

To use swift-format, follow these steps:

  1. Install swift-format:

    git clone https://github.com/apple/swift-format.git
cd swift-format
swift build -c release

  2. Add the built binary to your PATH or use it directly:

    /path/to/swift-format/build/release/swift-format format --in-place /path/to/your/swift/file.swift

  3. To use as a library, add this to your Package.swift:

    dependencies: [
    .package(url: "https://github.com/apple/swift-format.git", .branch("main"))
]

Competitor Comparisons

swiftlang logo

swift-syntax

3,187

A set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.

Pros of swift-syntax

  • More focused on parsing and analyzing Swift code structure
  • Provides a lower-level API for working with Swift syntax trees
  • Offers greater flexibility for custom syntax analysis and manipulation

Cons of swift-syntax

  • Requires more manual work to implement formatting rules
  • Less out-of-the-box functionality for code formatting
  • Steeper learning curve for basic formatting tasks

Code Comparison

swift-syntax:

import SwiftSyntax

let sourceFile = try SyntaxParser.parse(source: "let x = 5")
let variableDecl = sourceFile.statements.first?.item as? VariableDeclSyntax
print(variableDecl?.bindings.first?.pattern)

swift-format:

import SwiftFormat

let formatter = SwiftFormatter(configuration: .default)
let formattedCode = try formatter.format(source: "let x=5", assumingFileURL: nil)
print(formattedCode)

swift-syntax focuses on parsing and analyzing Swift code structure, providing a lower-level API for working with syntax trees. It offers greater flexibility for custom syntax analysis and manipulation but requires more manual work to implement formatting rules.

swift-format, on the other hand, is specifically designed for code formatting and provides more out-of-the-box functionality for this purpose. It has a simpler API for basic formatting tasks but may be less flexible for complex custom formatting requirements.

realm logo

SwiftLint

18,578

A tool to enforce Swift style and conventions.

Pros of SwiftLint

  • More extensive rule set with over 200 built-in rules
  • Highly customizable with the ability to enable/disable rules and create custom rules
  • Integrates well with popular IDEs and CI systems

Cons of SwiftLint

  • Can be slower for large projects due to the extensive rule set
  • May require more initial setup and configuration to tailor to project needs
  • Some rules might be overly opinionated or not align with all coding styles

Code Comparison

SwiftLint configuration example:

disabled_rules:
  - trailing_whitespace
opt_in_rules:
  - empty_count
  - missing_docs
line_length: 120

swift-format configuration example:

{
  "version": 1,
  "lineLength": 100,
  "indentation": {
    "spaces": 2
  }
}

Both tools aim to improve Swift code quality, but SwiftLint offers more granular control and a wider range of rules, while swift-format provides a more standardized approach with official backing from the Swift project. SwiftLint may be preferred for projects requiring extensive customization, while swift-format might be better suited for those seeking a more uniform, out-of-the-box solution.

nicklockwood logo

SwiftFormat

7,807

A command-line tool and Xcode Extension for formatting Swift code

Pros of SwiftFormat

  • More extensive set of formatting rules and options
  • Faster execution time for large codebases
  • Better integration with popular IDEs and text editors

Cons of SwiftFormat

  • Less official support from Apple
  • May not always align perfectly with Swift's official style guide
  • Requires manual installation and setup

Code Comparison

SwiftFormat:

let array = [1, 2, 3, 4, 5]
let result = array.map { $0 * 2 }.filter { $0 > 5 }

swift-format:

let array = [1, 2, 3, 4, 5]
let result = array
  .map { $0 * 2 }
  .filter { $0 > 5 }

SwiftFormat tends to keep chained method calls on a single line, while swift-format often breaks them into multiple lines for improved readability.

Both tools aim to improve code consistency and readability, but they differ in their approach and level of customization. SwiftFormat offers more flexibility and a wider range of formatting options, making it popular among developers who prefer fine-grained control over their code style. On the other hand, swift-format, being developed by the Swift team at Apple, adheres more closely to the official Swift style guide and may be preferred for projects that prioritize alignment with Apple's standards.

swiftlang logo

swift-evolution

15,342

This maintains proposals for changes and user-visible enhancements to the Swift Programming Language.

Pros of swift-evolution

  • Focuses on the Swift language evolution process, providing a centralized place for proposals and discussions
  • Allows community involvement in shaping the future of Swift
  • Contains detailed proposals with rationale, design, and implementation details

Cons of swift-evolution

  • Not directly related to code formatting or style enforcement
  • May be overwhelming for developers only interested in current Swift features
  • Requires more time and effort to navigate and understand proposals

Code comparison

While a direct code comparison isn't relevant due to the different purposes of these repositories, here's an example of how they might relate:

swift-evolution proposal:

extension Collection where Element: Comparable {
    func min(by areInIncreasingOrder: (Element, Element) throws -> Bool) rethrows -> Element?
}

swift-format implementation:

extension Collection where Element: Comparable {
  func min(
    by areInIncreasingOrder: (Element, Element) throws -> Bool
  ) rethrows -> Element? {
    // Implementation
  }
}

swift-format focuses on consistent code formatting, while swift-evolution proposes and discusses language features like the one shown above.

apple logo

swift-argument-parser

3,308

Straightforward, type-safe argument parsing for Swift

Pros of swift-argument-parser

  • Focused specifically on command-line argument parsing, making it more specialized and potentially easier to use for this purpose
  • Provides a declarative API using property wrappers, allowing for clean and intuitive command definitions
  • Offers automatic generation of help text and error messages

Cons of swift-argument-parser

  • Limited to command-line argument parsing, whereas swift-format provides a broader set of formatting capabilities
  • May require more setup for complex command structures compared to swift-format's configuration-based approach
  • Less integrated with Swift's standard library and toolchain

Code Comparison

swift-argument-parser:

struct Example: ParsableCommand {
    @Argument(help: "The name to greet")
    var name: String

    func run() throws {
        print("Hello, \(name)!")
    }
}

swift-format:

import SwiftFormatConfiguration

let configuration = Configuration()
configuration.indentation = .spaces(4)
configuration.lineLength = 100

let formatter = Formatter(configuration: configuration)
let formattedSource = try formatter.format(source: inputSource)

The code examples demonstrate the different focus areas of each library. swift-argument-parser provides a declarative way to define command-line arguments, while swift-format offers configuration options for code formatting.

swiftlang logo

swift-package-manager

9,727

The Package Manager for the Swift Programming Language

Pros of Swift Package Manager

  • More comprehensive functionality for managing dependencies and building Swift projects
  • Integrated with the Swift ecosystem and Xcode
  • Supports a wide range of platforms, including iOS, macOS, and Linux

Cons of Swift Package Manager

  • Larger and more complex codebase, potentially harder to contribute to
  • Slower development cycle due to its broader scope and integration with Swift

Code Comparison

Swift Package Manager:

import PackageDescription

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/example/example-package.git", from: "1.0.0"),
    ],
    targets: [
        .target(name: "MyTarget", dependencies: ["ExamplePackage"]),
    ]
)

Swift Format:

import SwiftFormatConfiguration

let configuration = Configuration()
configuration.indentation = .spaces(4)
configuration.lineLength = 100

Swift Package Manager is a comprehensive tool for managing Swift projects and dependencies, while Swift Format focuses specifically on code formatting. Swift Package Manager offers broader functionality but may be more complex, whereas Swift Format is more specialized and potentially easier to use for its specific purpose.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

swift-format

swift-format provides the formatting technology for SourceKit-LSP and the building blocks for doing code formatting transformations.

This package 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 default Swift code style guidelines have yet been proposed. The style that is currently applied by swift-format is 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.

Matching swift-format to Your Swift Version

Swift 5.8 and later

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 508.0.0, not 0.50800.0.

Swift 5.7 and earlier

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 ReleaseSwift Versionswift-format Branch / Tags
–Swift at mainmain
Xcode 14.0Swift 5.7release/5.7 / 0.50700.x
Xcode 13.3Swift 5.6release/5.6 / 0.50600.x
Xcode 13.0–13.2Swift 5.5swift-5.5-branch / 0.50500.x
Xcode 12.5Swift 5.4swift-5.4-branch / 0.50400.x
Xcode 12.0–12.4Swift 5.3swift-5.3-branch / 0.50300.x
Xcode 11.4–11.7Swift 5.2swift-5.2-branch / 0.50200.x
Xcode 11.0–11.3Swift 5.1swift-5.1-branch

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

Getting swift-format

If you are mainly interested in using swift-format (rather than developing it), then you can get it in three different ways:

Included in Xcode

Xcode 16 and above include swift-format in the toolchain. You can run swift-format from anywhere on the system using swift format (notice the space instead of dash). To find the path at which swift-format is installed, run xcrun --find swift-format.

Installing via Homebrew

Run brew install swift-format to install the latest version.

Building from source

Install swift-format using the following commands:

VERSION=510.1.0  # replace this with the version you need
git clone https://github.com/swiftlang/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 .build/release/swift-format.

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.

Command Line Usage

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.

Formatting

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

The 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 out the 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.

Linting

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

The 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 are detected.

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.

Options Supported by Formatting and Linting

The following options are supported by both the format and lint subcommands:

  • --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 diagnostics.

  • --color-diagnostics/--no-color-diagnostics: By default, swift-format 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 terminal.

  • --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 swift-format dump-configuration).

  • --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 multiple cores.

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

Viewing the Default Configuration

swift-format dump-configuration

The 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.

Configuring the Command Line Tool

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 output.

If the --configuration <file> option is passed to swift-format, then that configuration will be used unconditionally and the file system will not be searched.

See Documentation/Configuration.md for a description of the configuration file format and the settings that are available.

Miscellaneous

Running swift-format -v or swift-format --version will print version information about swift-format version and then exit.

API Usage

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 SwiftFormat API and receive perfectly formatted code as output.

Please see the documentation in the SwiftFormatter and SwiftLinter classes for more information about their usage.

Checking Out the Source Code for Development

The 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 main.

If you are interested in developing swift-format, there is additional documentation about that here.

Contributing

Contributions to Swift are welcomed and encouraged! Please see the Contributing to Swift guide.

Before submitting the pull request, please make sure you have tested your changes and that they follow the Swift project guidelines for contributing code.

To be a truly great community, Swift.org needs to welcome developers from all walks of life, with different backgrounds, and with a wide range of experience. A diverse and friendly community will have more great ideas, more unique perspectives, and produce more great code. We will work diligently to make the Swift community welcoming to everyone.

To give clarity of what is expected of our members, Swift has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and we think it articulates our values well. For more, see the Code of Conduct.