プロジェクトへのBlackの導入

注意

このガイドは未完成です。貢献は大歓迎であり、深く感謝いたします！

git blameを台無しにしない

Blackのような自動コードフォーマッターへの移行に対する長年の議論は、移行がgit blameの出力を混乱させるということです。これは正当な議論でしたが、Gitバージョン2.23以降、Gitは--ignore-revオプションを使用して、blameでのリビジョンの無視をネイティブにサポートしています。--ignore-revs-fileオプションを使用して、無視するリビジョンのリストをファイルに渡すこともできます。blameを割り当てる際、リビジョンによって行われた変更は無視されます。無視されたリビジョンによって変更された行は、それらの行を変更した前のリビジョンがblameされます。

したがって、プロジェクトのコードスタイルをBlackに移行する場合は、すべてを再フォーマットし、変更をコミットします（できれば1つの大規模なコミットで）。次に、完全な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 blameのすべての呼び出しで、ファイルにリストされているリビジョンを自動的に無視するようにgitを設定することもできます。

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

1つの注意点は、GitLabのような一部のオンラインGitリポジトリが、ネイティブのblame UIを使用したリビジョンの無視をまだサポートしていないことです。したがって、これらのプラットフォームでは、blame情報が再フォーマットコミットで散らかってしまいます。（この機能が必要な場合は、GitLabに関する未解決の問題があります）。ただし、GitHubは、blameビューで.git-blame-ignore-revsをデフォルトでサポートしています。