[ Space Commander]

[ Space Commander] 提供了工具，使得 iOS 开发团队可以使用统一样式格式提交 Objective-C 代码到 Git 仓库，而无需任何手动调整。

您可以使用它来：

• 在提交代码前强制执行格式规范。
• 使用单个命令格式化代码（既可以单独文件也可以是整个仓库）。
• 如果分支中有未格式化的代码，则构建失败（在拉取请求期间）。

在 Square，[ Space Commander] 将 iOS 开发流程（特别是在拉取请求方面）简化了。应用格式规范不再需要人工开发者注意力；这些时间可以更好地用来做其他事情！

您可能希望从您的团队特定的格式规则中分叉 [ Space Commander]（更多信息见下文），或者克隆以享受 Square 的 Objective-C 格式化版本。

本地安装

要从您的仓库中添加格式化预提交检查，请从目标仓库运行 path/to/spacecommander/setup-repo.sh。

用法

执行 setup-repo.sh 后，每次提交之前会自动运行格式化检查。

要格式化和就地修改单个文件，运行 format-objc-file.sh <file>。要格式化而不修改，运行 format-objc-file-dry-run.sh <file>

要就地格式化仓库中所有的Objective-C文件，运行 format-objc-files-in-repo.sh。

细节

为了安装pre-commit钩子，项目中的每个开发者都运行设置脚本。这将安装一个precommit钩子，用于在提交成功之前验证代码格式。

如果在提交过程中出现格式化错误，可以运行一个自动修复代码的脚本来成功提交。

在Square，这个格式化仓库被用作一个更大的iOS项目的子模块，这样格式化规则和脚本就被锁定在父仓库的一个版本上。这样，我们可以在构建过程中检查格式化，如果格式化不当前则构建失败（我们还可以无困难地检出旧的SHAs）。

clang-format期望自定义规则文件存在于命令运行的同一目录中，因此在目标仓库中添加了一个规则文件的.gitignore-d符号链接。这是一个符号链接，以便开发者只需更新格式化仓库的git SHA即可从上游获取最新的格式化规则。

配置

如果要仅格式化所选目录中的文件，在名为.formatting-directory的文件中指定每个目录的名称，用新行分隔（不包含空白符）。否则，检查repo中跟踪的所有Objective-C文件。

要忽略目录中的文件，将每个目录的名称添加到名为.formatting-directory-ignore的文件中的新行。

要修改格式化输出，请编辑以下内容

• .clang-format用于内置的clang-format选项。
• format-objc-file-dry-run.sh和format-objc-file.sh用于在custom/中实现的规则。
• Testing Support/文件以验证您的更改。

如果格式化程序应忽略文件，则将#pragma Formatter Exempt或// MARK: Formatter Exempt作为文件的第一行。

用于pull请求验证的安装

以下说明是 Square 特定的。我们使用一个名为 mobuild 的构建系统。我们使用的钩子，可以集成到其他构建系统中，是 format-objc-mobuild

如果您想要将样式检查作为合并拉取请求的强制步骤，请按照以下操作：

• 将此仓库添加为 cocoapod，或将其作为 Scripts/ 目录中的子模块添加。
• 确保您的仓库在顶级目录中设置了 .sqiosbuild.json 和 .stashkins 文件（更多信息请参阅 Square Wiki 页面 关于 Mobuild 的所有内容）。
• 构建机器设置了检查上述条件，如果条件满足，则自动运行 format-objc-mobuild。
• 通过修改 Objective-C 文件打开一个 PR，以验证这些检查是否正在运行。

更新样式选项

通过修改 .clang-format 来更改格式化策略。可用的样式选项列在 Clang 网站 上。

请还更新 UnformattedExample.m（位于 ./Testing Support/ 下），其中包含您格式化更改应修复的代码示例。

然后更新 FormattedExample.m（在同一位置），并按预期结果，通过运行简单测试来验证您的更改是否产生所需的输出： ./test.sh

自定义格式化器

clang-format 实在太棒了，我们非常喜欢它，但它有一些限制。我们在 custom/ 中添加了一些自定义格式化功能，通过脚本实现。如果您在 custom/ 中添加了一个自定义的文件格式化脚本，请将其在 format-objc-file.sh 和 format-objc-file-dry-run.sh 中调用，并将输入/输出示例添加到 Testing Support/ 中的文件。

不期望的结果？

格式化器不能做到一切。它有时可能会产生不理想的结果，这种情况下，您可以选择以下操作：

• 重构代码以生成对格式化器来说更简单、更不易混淆的行。
• 使用 // clang-format off 和 // clang-format on 选择性地启用/禁用文件中的特定行的 clang-format。
• 将 #pragma Formatter Exempt 或 // MARK: Formatter Exempt 作为文件的第一行，这样它就不会被格式化。
• 维斯瓦娃·辛波斯卡 曾经说，“所有的不完美，如果以小剂量呈现，都更容易忍受。” [Space Commander] 将几乎消除所有的格式不完美，但您可能需要偶尔忍受与预期结果有所偏差的情况。

参与贡献

我们很高兴您对 [Space Commander] 兴趣浓厚，并希望看到您如何将其发扬光大。在提交拉取请求之前，请阅读我们的贡献指南。

感谢，祝您格式化愉快！