Introducing Black to your project¶
This guide is incomplete. Contributions are welcomed and would be deeply appreciated!
Avoiding ruining git blame¶
A long-standing argument against moving to automated code formatters like Black is
that the migration will clutter up the output of
git blame. This was a valid argument,
but since Git version 2.23, Git natively supports
ignoring revisions in blame
--ignore-rev option. You can also pass a file listing the revisions to ignore
--ignore-revs-file option. The changes made by the revision will be ignored
when assigning blame. Lines modified by an ignored revision will be blamed on the
previous revision that modified those lines.
So when migrating your project’s code style to Black, reformat everything and commit the changes (preferably in one massive commit). Then put the full 40 characters commit identifier(s) into a file.
# Migrate code style to Black 5b4ab991dede475d393e9d69ec388fd6bd949699
Afterwards, you can pass that file to
git blame and see clean and meaningful 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)
You can even configure
git to automatically ignore revisions listed in a file on every
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
The one caveat is that GitHub and GitLab do not yet support ignoring revisions using their native UI of blame. So blame information will be cluttered with a reformatting commit on those platforms. (If you’d like this feature, there’s an open issue for GitLab and please let GitHub know!)