]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Document git's ignore-revs-file feature (#1419)
authorRichard Si <63936253+ichard26@users.noreply.github.com>
Sat, 16 May 2020 20:22:46 +0000 (16:22 -0400)
committerGitHub <noreply@github.com>
Sat, 16 May 2020 20:22:46 +0000 (13:22 -0700)
* 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>
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).
 
 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
 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](#used-by) by many projects, small and big. It