swift-format

swift-format 为 SourceKit-LSP 提供了格式化技术，并为进行代码格式化转换提供了构建模块。

此软件包可以用作命令行工具，也可以作为 Swift Package Manager 依赖项链接到其他应用程序中，并通过API 调用。

注意：尚未提出默认的 Swift 代码样式指南。目前 swift-format 应用的样式只是一种可能性，提供此代码是为了可以在真实代码上进行测试，并通过修改进行实验。

从 Swift 5.8 开始，swift-format 依赖于 SwiftSyntax 版本，该版本的解析器已在 Swift 中重写，不再依赖 Swift 工具链中的库。

此更改允许 swift-format 使用任何可以编译它的 Swift 版本进行构建、开发和运行，使其与支持特定语法的版本脱钩。但是，早期版本的 swift-format 仍然无法识别在更高版本的语言和解析器中添加的新语法。

另请注意，版本编号方案已更改为与 SwiftSyntax 匹配；swift-format 的 5.8 版本是 508.0.0，而不是 0.50800.0。

swift-format 版本 0.50700.0 及更早版本依赖于 SwiftSyntax 版本，这些版本使用作为 Swift 工具链一部分发布的独立解析库。使用这些版本时，您应该检出并从与您使用的 Swift 版本兼容的发布标签或分支构建 swift-format。

swift-format 和 SwiftSyntax 的主要版本和次要版本组件必须相同——这在 Package.swift 中的 SwiftSyntax 依赖项中表达——并且这些版本组件必须与已安装并用于构建和运行格式化程序的 Swift 工具链匹配

例如，如果您正在使用 Xcode 13.3 (Swift 5.6)，您将需要 swift-format 0.50600.0。

如果您主要对使用 swift-format 感兴趣（而不是开发它），那么您可以通过三种不同的方式获取它

Swift 6（包含在 Xcode 16 中）及更高版本在工具链中包含 swift-format。您可以使用 swift format （注意空格而不是短划线）从系统上的任何位置运行 swift-format。要查找 swift-format 在 Xcode 中安装的路径，请运行 xcrun --find swift-format。

运行 brew install swift-format 以安装最新版本。

使用以下命令安装 swift-format

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

请注意，上面的 git checkout 命令会将存储库置于“分离 HEAD”状态。如果构建和运行该工具是您要做的全部事情，那么这很好。

构建完成后，swift-format 可执行文件将位于 .build/release/swift-format。

要测试格式化程序是否已成功构建并且与您的 Swift 工具链兼容，您还可以运行以下命令

swift test --parallel

我们建议使用 --parallel 标志来加速测试运行，因为有大量测试。

swift-format 的一般调用语法如下

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

该工具支持多个子命令，每个子命令都有自己的选项，如下所述。还可以通过运行 swift-format --help 获取可用子命令的描述，并且可以通过在子命令名称后使用 --help 标志来获取特定子命令的描述；例如，swift-format lint --help。

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

format 子命令格式化一个或多个 Swift 源文件（如果命令行上未给出文件路径，则从标准输入格式化源代码）。写出 format 子命令是可选的；如果没有给出其他子命令，它是默认行为。

此子命令支持所有常见的 lint 和 format 选项，以及以下仅格式化选项

• -i/--in-place：格式化时覆盖输入文件，而不是将结果打印到标准输出。在覆盖原始文件之前，不会创建原始文件的备份。

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

lint 子命令检查一个或多个 Swift 源文件（如果命令行上未给出文件路径，则从标准输入检查源代码）是否存在样式违规，并将检测到的任何违规的诊断信息打印到标准错误。

此子命令支持所有常见的 lint 和 format 选项，以及以下仅 lint 选项

• -s/--strict：如果指定此选项，lint 警告将导致工具以非零退出代码（失败）退出。默认情况下，lint 警告不会阻止成功退出；只有致命错误（例如，尝试 lint 不存在的文件）才会导致工具退出失败。

format 和 lint 子命令都支持以下选项

• --assume-filename <path>：从标准输入进行 lint 或格式化时，应在诊断中使用的文件路径。如果未提供此选项，则 <stdin> 将用作诊断中打印的文件名。

• --color-diagnostics/--no-color-diagnostics：默认情况下，如果标准错误连接到终端，swift-format 将以彩色打印诊断信息，否则不使用颜色（例如，如果标准错误被重定向到文件）。这些标志可用于强制启用或禁用颜色，而与输出是否转到终端无关。

• --configuration <file>：包含 swift-format 的可配置设置的 JSON 文件的路径。如果省略，则使用默认配置（可以通过运行 swift-format dump-configuration 查看）。

• --ignore-unparsable-files：如果指定此选项，并且源文件包含语法错误或无法被 Swift 语法解析器成功解析，则将忽略该文件（不会发出诊断信息，也不会对其进行格式化）。如果没有此选项，则会为任何无法解析的文件发出错误。

• -p/--parallel：跨多个核心并行同时处理文件。

• -r/--recursive：如果指定，则该工具将处理命令行上列出的任何目录及其后代中的 .swift 源文件。如果没有此标志，则在命令行上列出目录是错误的。

swift-format dump-configuration

dump-configuration 子命令将默认配置以 JSON 格式转储到标准输出。这可以通过将其重定向到文件并进行编辑来简化自定义配置的生成。

对于正在检查或格式化的任何源文件，swift-format 都会在同一目录中查找名为 .swift-format 的 JSON 格式文件。如果找到，则加载该文件以确定工具的配置。如果未找到该文件，则在父目录中查找，依此类推。

如果未找到配置文件，则使用默认配置。可以通过运行 swift-format dump-configuration 查看默认配置中的设置，这将将其转储到标准输出。

如果将 --configuration <configuration> 选项传递给 swift-format，则将无条件地使用该配置，并且不会搜索文件系统。

有关配置格式和可用设置的说明，请参阅 Documentation/Configuration.md。

dump-configuration 子命令接受 --effective 标志。如果设置，它将转储如果从当前工作目录执行 swift-format 将使用的配置，并考虑如上所述的 .swift-format 文件或 --configuration 选项。

运行 swift-format -v 或 swift-format --version 将打印有关 swift-format 版本的版本信息，然后退出。

swift-format 可以轻松集成到用 Swift 编写的其他工具中。用户可以依赖 swift-format 作为 Swift Package Manager 依赖项并导入 SwiftFormat 模块，而不是通过生成子进程来调用格式化程序，该模块包含格式化程序的诊断和更正行为的入口点。

格式化行为由 SwiftFormatter 类提供，lint 行为由 SwiftLinter 类提供。这些 API 可以传递 Swift 源文件 URL 或表示 SwiftSyntax 语法树的 Syntax 节点。后一种功能对于编写代码生成器特别有用，因为它显着减少了生成器需要关注添加到其创建的语法节点的 trivia 量。相反，它可以将内存中的语法树传递给 SwiftFormat API，并接收完美格式化的代码作为输出。

有关其用法的更多信息，请参阅 SwiftFormatter 和 SwiftLinter 类中的文档。

main 分支用于开发。拉取请求应创建为合并到 main 分支中；在合并到 main 后，可以将低风险且与最新发布分支兼容的更改 cherry-pick 到该分支中。

如果您有兴趣开发 swift-format，则可以在此处找到有关该主题的更多文档。

欢迎并鼓励为 Swift 做出贡献！请参阅Swift 贡献指南。

在提交拉取请求之前，请确保您已测试了您的更改，并且它们遵循 Swift 项目的代码贡献指南。

为了成为一个真正伟大的社区，Swift.org 需要欢迎来自各行各业、具有不同背景和各种经验的开发人员。一个多元化和友好的社区将有更多的好主意、更独特的视角，并产生更多的优秀代码。我们将努力使 Swift 社区欢迎所有人。

为了明确我们对成员的期望，Swift 采用了 Contributor Covenant 定义的行为准则。这份文档在许多开源社区中使用，我们认为它很好地表达了我们的价值观。有关更多信息，请参阅行为准则。