actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Richard Si 2020-05-16 16:22:46 -04:00 committed by GitHub
parent 97060a4f18
commit 12e857f24c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -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 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). [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 ### NOTE: This is a beta product
_Black_ is already [successfully used](#used-by) by many projects, small and big. It _Black_ is already [successfully used](#used-by) by many projects, small and big. It