# 客户仓库从 Black 换到 Ruff，不必提上千行的 PR

> Astral 称 Ruff 对 Black 格式代码兼容度超 99.9%，diff 小到客户团队能真正审完。

原文: https://fdetimes.net/zh/tools/ruff-lint-format-client-python-repo/

到客户那里的第一周，你打开对方的 Python 仓库，一下子看到三样东西：一个 Flake8 配置文件、一个 isort 钩子，还有 CI 里一行 Black，没人说得清它是否还在运行。你想清理一下，但一个改动几千行的“统一代码风格”PR，足以让客户团队一上来就对你起疑。

Ruff 适合这种场景，因为它的格式化器本就是作为 Black 的替代品设计的，在已用 Black 格式化的代码上，输出几乎完全一致。

Astral 的 Charlie Marsh 表示，在这类项目上，按改动行数计算，Ruff 的兼容度超过 99.9%。换句话说，工具换了，代码几乎不用动。

对前线部署工程师（FDE）来说，这一点比速度更重要。几十行的 PR，客户能读完再批准；几千行的 PR，客户只能选择信任或拒绝。

## 一个二进制文件替代一堆工具

Ruff 是用 Rust 编写的代码检查与格式化工具，采用 MIT 许可证发布，由打造 uv 和 ty 的 Astral 团队开发。官方文档称，Ruff 可以替代 Flake8 及其数十个插件，以及 Black、isort、pydocstyle、pyupgrade、autoflake 等工具。

同一份文档称，Ruff 比现有的代码检查和格式化工具快 10 到 100 倍，并内置缓存，未改动的文件不会重新分析。单看格式化器，Astral 报告的速度是 Black 的 30 倍以上。

在客户仓库里，这样的速度让你可以和对方团队坐在一起，当场检查整个代码库，不必等 CI。不过更大的好处是，仓库最终只有一个地方放配置，不再是每个工具一个文件。

## 先测量，再做四个小提交

设想一个内部仓库：`legacy/` 目录没人敢碰，`services/` 目录还在活跃开发。稳妥的做法是先测量再动手，然后把工作拆成四个提交，每个只做一件事。

测量不产生提交。`ruff check .` 只列出违规项，不做任何修复，因为只有传入 `--fix` 参数时 Ruff 才会修复。输出结果就是一张技术债地图，可以直接带到和客户的会上。

第一个提交加入 Ruff 配置，并标记已有技术债，而不是去修。`ruff check . --add-noqa` 会在每一行当前违规的代码上插入 `noqa` 注释。从此只有新代码会被拦下。需要长期豁免的目录，在 `pyproject.toml` 中用 `per-file-ignores`：

```toml
[tool.ruff.lint.per-file-ignores]
"legacy/*" = ["E501"]
```

第二个提交是 `ruff format`，单独提交，不夹带其他改动。这个提交存在之后才有它的哈希，所以第三个提交是后续提交：添加一个 `.git-blame-ignore-revs` 文件，写入这个哈希，让 GitHub 的 blame 视图跳过格式化提交。

这样，任何人查看历史时，看到的仍是每行代码的作者，而不是运行格式化工具的人。

**要点:** 只格式化一次，单独提交，然后在 git blame 中隐藏它。

最后一个提交是 `ruff check --fix`。默认情况下，Ruff 只应用被归为安全的修复。可能改变代码行为的修复还需要加上 `--unsafe-fixes`。在客户仓库里，这个参数只留给小型、逐个审查的 PR。

## 什么时候 diff 仍会暴涨？

99.9% 以上这个数字，只适用于已用 Black 格式化的代码。Ruff 文档明确说明，格式化器在少数地方有意与 Black 不同，比如代码块开头的空行、f-string 和单元素元组。如果客户仓库从没用过 Black，第一次格式化可能产生相当大的 diff。

所以要先问客户的是“CI 真的在跑 Black 吗？”，而不是“你们用什么代码检查工具？”。如果在跑，可以预期 diff 很小；如果没有，就提前告知对方可能会有一个很大的格式化提交，这也正是需要 `.git-blame-ignore-revs` 的原因。

## monorepo 的配置陷阱

Ruff 通过分层配置支持 monorepo，配置可写在 `pyproject.toml`、`ruff.toml` 或 `.ruff.toml` 中。有一个细节很容易让你白白耗掉一个下午：对每个文件，Ruff 使用目录树中离它最近的配置文件，不会跨文件合并设置。

假设 `services/billing/` 有自己的 `ruff.toml`，只为了改行宽。那么你在根目录 `pyproject.toml` 中设置的所有规则，对这个目录都不再生效。在下结论说“Ruff 漏报了”之前，先确认这个文件实际用的是哪份配置。

## 先学什么

先学“测量 + 四个提交”这套流程，再去学规则清单。客户仓库里的风险在于推行过程，而不在于选了哪些规则。之后读一读列出 Ruff 与 Black 差异的那一页，客户问某一行为什么变了，答案就在那里。

写在简历上，“将一个 Python 仓库从 Flake8、isort 和 Black 迁移到 Ruff，格式化 diff 控制在 X 行以内，且未破坏 git blame”这样一行，远比简单写“精通 Ruff”有分量。

快的工具能帮你省几分钟。一个客户能读懂的小 PR，才能赢得他们的信任。

**本周动手试试:**

- 克隆一个使用 Black 的开源 Python 仓库，在单独分支上运行 ruff format，并用 git diff --stat 统计改动行数。
- 在同一个仓库上运行 ruff check --add-noqa 并提交，然后写一段违反规则的新代码，确认只有新代码被标出。
- 格式化提交之后，新建一个提交，添加包含格式化提交哈希的 .git-blame-ignore-revs 文件，再到 GitHub 上打开 git blame 查看效果。

## 信源

- [Ruff](https://docs.astral.sh/ruff/)

- [GitHub - astral-sh/ruff](https://github.com/astral-sh/ruff)

- [The Ruff Formatter | Ruff](https://docs.astral.sh/ruff/formatter/)

- [The Ruff Formatter](https://astral.sh/blog/the-ruff-formatter)

- [The Ruff Linter | Ruff](https://docs.astral.sh/ruff/linter/)

- [Configuring Ruff | Ruff](https://docs.astral.sh/ruff/configuration/)

- [Viewing and understanding files](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-and-understanding-files#ignore-commits-in-the-blame-view)
