将 *Black* 引入您的项目

注意

本指南尚未完善。欢迎贡献，您的贡献将不胜感激！

避免破坏 git blame

长期以来，反对转向 *Black* 等自动化代码格式化程序的一个论点是，迁移将使 git blame 的输出变得杂乱无章。这曾经是一个有效的论点，但自 Git 版本 2.23 起，Git 本身支持使用 --ignore-rev 选项 在 blame 中忽略修订版。您还可以使用 --ignore-revs-file 选项传递一个包含要忽略的修订版的列表文件。修订版所做的更改将在分配 blame 时被忽略。由被忽略的修订版修改的行将被指责为先前修改这些行的修订版。

因此，在将项目的代码风格迁移到 *Black* 时，请重新格式化所有内容并将更改提交（最好在一个大的提交中）。然后将完整的 40 个字符提交标识符放入通常称为 .git-blame-ignore-revs 的文件，该文件位于项目目录的根目录中。

# Migrate code style to Black
5b4ab991dede475d393e9d69ec388fd6bd949699

之后，您可以将该文件传递给 git blame 并查看干净且有意义的 blame 信息。

$ git blame important.py --ignore-revs-file .git-blame-ignore-revs
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)

您甚至可以配置 git 以在每次调用 git blame 时自动忽略文件中列出的修订版。

$ git config blame.ignoreRevsFile .git-blame-ignore-revs

**唯一需要注意的是，一些在线 Git 仓库（如 GitLab）尚未支持使用其本机 blame UI 忽略修订版。** 因此，blame 信息将在这些平台上包含重新格式化提交的杂乱内容。（如果您需要此功能，有一个针对 GitLab 的开放问题）。但是，GitHub 默认支持 .git-blame-ignore-revs，用于 blame 视图。