From 59e8936768889f583488df609c45302da8e88507 Mon Sep 17 00:00:00 2001
From: Shantanu <12621235+hauntsaninja@users.noreply.github.com>
Date: Thu, 3 Aug 2023 18:46:08 -0700
Subject: [PATCH] Document pre-commit mirror (#3828)

---
 .pre-commit-hooks.yaml                      |  2 ++
 CHANGES.md                                  |  5 +++++
 docs/integrations/source_version_control.md | 13 ++++++++-----
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index 1379570..a1ff41f 100644
--- 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 709c767..1de0879 100644
--- 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 a9d33d2..24e7328 100644
--- 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
-- 
2.39.5