Document pre-commit mirror (#3828)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 137957045a6c938eec1408ca9af8ba47d59f4caa..a1ff41fded87d199692f1b68119c5bb390bbab5c 100644 (file)
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -1,3 +1,5 @@
+# Note that we recommend using https://github.com/psf/black-pre-commit-mirror instead
+# This will work about 2x as fast as using the hooks in this repository
 - id: black
   name: black
   description: "Black: The uncompromising Python code formatter"

diff --git a/CHANGES.md b/CHANGES.md
index 709c767b3298115541552eed19db3ea98b2ebfc5..1de08792f7532b783db469fe7c97341a836f8028 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -44,6 +44,11 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- Black now has an
+  [official pre-commit mirror](https://github.com/psf/black-pre-commit-mirror). Swapping
+  `https://github.com/psf/black` to `https://github.com/psf/black-pre-commit-mirror` in
+  your `.pre-commit-config.yaml` will make Black about 2x faster (#3828)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md
index a9d33d2d85307cb89cabb4d05043b5b045ebdc71..24e732848f1487b96b4e21d6750a01b5529ff383 100644 (file)
--- a/docs/integrations/source_version_control.md
+++ b/docs/integrations/source_version_control.md
@@ -6,7 +6,8 @@ Use [pre-commit](https://pre-commit.com/). Once you
 
 ```yaml
 repos:
-  - repo: https://github.com/psf/black
+  # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
+  - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.7.0
     hooks:
       - id: black
@@ -17,8 +18,10 @@ repos:
         language_version: python3.11
 ```
 
-Feel free to switch out the `rev` value to something else, like another
-[tag/version][black-tags] or even a specific commit. Although we discourage the use of
+Feel free to switch out the `rev` value to a different version of Black.
+
+Note if you'd like to use a specific commit in `rev`, you'll need to swap the repo
+specified from the mirror to https://github.com/psf/black. We discourage the use of
 branches or other mutable refs since the hook [won't auto update as you may
 expect][pre-commit-mutable-rev].
 
@@ -30,7 +33,8 @@ include Jupyter Notebooks. To use this hook, simply replace the hook's `id: blac
 
 ```yaml
 repos:
-  - repo: https://github.com/psf/black
+  # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
+  - repo: https://github.com/psf/black-pre-commit-mirror
     rev: 23.7.0
     hooks:
       - id: black-jupyter
@@ -45,6 +49,5 @@ repos:
 The `black-jupyter` hook became available in version 21.8b0.
 ```
 
-[black-tags]: https://github.com/psf/black/tags
 [pre-commit-mutable-rev]:
   https://pre-commit.com/#using-the-latest-version-for-a-repository