Why does Black insist on reformatting my entire project?

Some thoughts about why Black recommends adopting it by reformatting your entire codebase in one go and refuses to do “region reformatting”. This started as a tweet but there’s a bit too much content for 280 characters.

For some users, one giant commit that reformats the world is an unpleasant thought. After all, it’s a “useless commit” and poisons git blame! I think that’s backwards.

First of all, it’s easy to ignore the particular commit while browsing git blame with the blame.ignoreRevsFile config option or --ignore-rev on the command line. Making all reformatting in just one commit makes it easier. But there’s an even more important advantage!

When you make this single reformatting commit, everything that comes after is semantic changes so your commit history is clean in the sense that it actually shows what changed in terms of meaning, not style. There are tools like darker that allow you to only reformat lines that were touched since the last commit. However, by doing that you forever expose yourself to commits that are a mix of semantic changes with stylistic changes, making it much harder to see what changed.

This also gives up Black’s design considerations that allow diffs to be as small as possible. But the worst thing that since you never made a single sweeping reformatting commit, you won’t ever be able to decouple formatting changes from semantic changes while browsing git history. This is why I’m advocating against mingling semantic changes with partial reformattings. This is why in my time at Facebook we reformatted over 20,000,000 lines of Python code to avoid the issues I outline above. Sure, this wasn’t exactly in one commit because our version control systems wouldn’t be able to handle that. In particular, I did reformat all of Instagram in a single weekend with Carl Meyer. It was glorious.

In the end I’m not your real dad. You can do what you want with your own projects. I’m just saying that Black insisting on you adopting it fully isn’t ideological. It’s rational. Sure, it’s radical but that much you already knew.

#Programming #Python