]> git.madduck.net Git - etc/vim.git/blob - docs/guides/introducing_black_to_your_project.md

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:

Port & upstream mypyc wheel build workflow (#3197)
[etc/vim.git] / docs / guides / introducing_black_to_your_project.md
1 # Introducing _Black_ to your project
2
3 ```{note}
4 This guide is incomplete. Contributions are welcomed and would be deeply
5 appreciated!
6 ```
7
8 ## Avoiding ruining git blame
9
10 A long-standing argument against moving to automated code formatters like _Black_ is
11 that the migration will clutter up the output of `git blame`. This was a valid argument,
12 but since Git version 2.23, Git natively supports
13 [ignoring revisions in blame](https://git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revltrevgt)
14 with the `--ignore-rev` option. You can also pass a file listing the revisions to ignore
15 using the `--ignore-revs-file` option. The changes made by the revision will be ignored
16 when assigning blame. Lines modified by an ignored revision will be blamed on the
17 previous revision that modified those lines.
18
19 So when migrating your project's code style to _Black_, reformat everything and commit
20 the changes (preferably in one massive commit). Then put the full 40 characters commit
21 identifier(s) into a file.
22
23 ```text
24 # Migrate code style to Black
25 5b4ab991dede475d393e9d69ec388fd6bd949699
26 ```
27
28 Afterwards, you can pass that file to `git blame` and see clean and meaningful blame
29 information.
30
31 ```console
32 $ git blame important.py --ignore-revs-file .git-blame-ignore-revs
33 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 1) def very_important_function(text, file):
34 abdfd8b0 (Alice Doe  2019-09-23 11:39:32 -0400 2)     text = text.lstrip()
35 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 3)     with open(file, "r+") as f:
36 7a1ae265 (John Smith 2019-04-15 15:55:13 -0400 4)         f.write(formatted)
37 ```
38
39 You can even configure `git` to automatically ignore revisions listed in a file on every
40 call to `git blame`.
41
42 ```console
43 $ git config blame.ignoreRevsFile .git-blame-ignore-revs
44 ```
45
46 **The one caveat is that some online Git-repositories like GitLab do not yet support
47 ignoring revisions using their native blame UI.** So blame information will be cluttered
48 with a reformatting commit on those platforms. (If you'd like this feature, there's an
49 open issue for [GitLab](https://gitlab.com/gitlab-org/gitlab/-/issues/31423)). This is
50 however supported by
51 [GitHub](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view),
52 currently in beta.