Document git's ignore-revs-file feature (#1419)

* Document git's ignore-revs-file feature

A long-standing counterargument against moving to automated code formatters
like Black is that the migration will clutter up the output of git blame.
This used to be a valid argument, but not anymore. Since git version 2.23,
git natively supports ignoring revisions in blame with the --ignore-rev
and --ignore-revs-file options.

This isn't documented in the Black documentation. It should be as it would
put old projects wanting to migrate to Black at ease since blame won't
be ruined.

* Add links so people can +1 on --ignore-revs-file support

* Fix wording

'Counterargument' was the wrong word since it means an objection to an objection. 'Argument' is the proper word I was looking for.

Co-authored-by: Cooper Lees <me@cooperlees.com>

diff --git a/README.md b/README.md
index 405eae618d30b94dde1bee2e5f42d19f1f6a807a..5357852654aed9b7c1cb4344ff0ec5faa160ea20 100644 (file)
--- a/README.md
+++ b/README.md
@@ -150,6 +150,50 @@ should be configured to neither warn about nor overwrite _Black_'s changes.
 Actual details on _Black_ compatible configurations for various tools can be found in
 [compatible_configs](https://github.com/psf/black/blob/master/docs/compatible_configs.md).
 
+### Migrating your code style without 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](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
+with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
+using the `--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 amd meaningful blame
+information.
+
+```
+$ 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
+call to `git blame`.
+
+```shell
+$ git config blame.ignoreRevsFile .git-blame-ignore-revs
+```
+
+**The one caveat is that GitHub and GitLab do not yet support ignoring revisions using
+in their native UI of blame.** So blame information will be cluttered with a reformating
+commit on those platforms. (If you'd like this feature, there's an open issue for
+[GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423) and please let GitHub
+know!)
+
 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](#used-by) by many projects, small and big. It