deprecate the --diff option

[asottile]

resolves #1389

[noamraph]

@asottile I would vote to un-deprecate this feature. I'm trying to improve the code style in my company, and as a first step I want to forbid commits that add new warnings. I hope that in the future I will be able to fix all style issues, but that will take a (long) while. Using the --diff option seems like the only way to prevent new style violations from being committed.

I understand that --diff is not perfect, as new warnings can be triggered. However, as it's a very useful feature, I suggest to replace the deprecation with a note explaining why new warnings might be introduced even if flake8 --diff didn't show anything.

[asottile]

it's fundamentally broken so it is being removed

I recommend you either:

• use a code formatter to fix the existing issues
• work file-by-file to fix issues

more on that: https://github.com/readme/guides/code-review