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.