chore: import upstream snapshot with attribution

docs/integrations/doctest_formatting.md

@@ -0,0 +1,102 @@
+# Doctest Formatting
+
+While _Black_ makes some decisions about styling for docstrings, it does not make any
+assumptions about the contents of documentation. Thus, executable Python code inside
+docstrings or documentation files (e.g. doctests), will not be formatted by _Black_.
+
+Listed below are tools that apply _Black_ formatting to code inside docstrings and
+documentation files.
+
+> Note: There are some observed inconsistencies between the below packages. Because of
+> this, we hesitate to make any recommendations. Any installed packages are installed at
+> your own risk. We also encourage anyone to contribute documentation for additional
+> packages that apply _Black_ formatting to doctests.
+
+## blacken-docs
+
+[`blacken-docs`](https://github.com/adamchainz/blacken-docs) is primarily used to apply
+_Black_ formatting to code in documentation files (e.g. `.rst`, `.md`, `.tex`).
+
+`blacken-docs` supports the following:
+
+- Python code blocks in Markdown, reStructuredText, and LaTeX files. Similar to
+  `blackdoc`, normal _Black_ formatting is applied, so doctests inside Python code
+  blocks will not be formatted.
+
+  ````md
+  ```python
+  print("Hello world!")
+  ```
+  ````
+
+  ```rst
+  .. code-block:: python
+      print("Hello world!")
+  ```
+
+  ```latex
+  \begin{minted}{python}
+  print("Hello world!")
+  \end{minted}
+  ```
+
+- Doctests inside Pycon code blocks in Markdown and reStructuredText. The code blocks
+  may be included in a `.md` or `.rst` file, or inside a docstring in a Python file.
+
+  ````md
+  ```python
+  >>> print("Hello world!")
+  ```
+  ````
+
+  ```rst
+  .. code-block:: pycon
+      >>> print("Hello world!")
+  ```
+
+  ````python
+  def add_one(n: int) -> int:
+      """
+      Examples
+      --------
+      ```pycon
+      >>> add_one(1) == 2
+      ```
+      """
+      return n + 1
+  ````
+
+## blackdoc
+
+[`blackdoc`](https://blackdoc.readthedocs.io/en/stable) is primarily used to apply
+_Black_ formatting to doctests in Python files. It will not format any file contents
+that are otherwise covered by _Black_.
+
+`blackdoc` supports the following:
+
+- Doctests in Python files.
+
+  ```python
+  def add_one(n: int) -> int:
+      """
+      Examples
+      --------
+      >>> add_one(1) == 2
+      """
+      return n + 1
+  ```
+
+- Python code blocks in Markdown or reStructuredText files. In these cases, normal
+  _Black_ formatting is applied, i.e., doctests inside Python code blocks will not be
+  formatted.
+
+  ````md
+  ```python
+  print("Hello world!")
+  ```
+  ````
+
+  ```rst
+  .. code-block:: python
+      print("Hello world!")
+  ```

docs/integrations/editors.md

@@ -0,0 +1,493 @@
+# Editor integration
+
+## Emacs
+
+Options include the following:
+
+- [emacs-python-black](https://github.com/wbolster/emacs-python-black)
+- [Blacken](https://github.com/pythonic-emacs/blacken)
+- [Elpy](https://elpy.readthedocs.io/en/stable/).
+
+## PyCharm/IntelliJ IDEA
+
+There are several different ways you can use _Black_ from PyCharm:
+
+1. Using the built-in _Black_ integration (PyCharm 2023.2 and later). This option is the
+   simplest to set up.
+1. As local server using the BlackConnect plugin. This option formats the fastest. It
+   spins up {doc}`Black's HTTP server </usage_and_configuration/black_as_a_server>`, to
+   avoid the startup cost on subsequent formats.
+1. As external tool.
+1. As file watcher.
+
+### Built-in _Black_ integration
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Go to `Preferences or Settings -> Tools -> Black` and configure _Black_ to your
+   liking.
+
+### As local server
+
+1. Install _Black_ with the `d` extra.
+
+   ```console
+   $ pip install 'black[d]'
+   ```
+
+1. Install
+   [BlackConnect IntelliJ IDEs plugin](https://plugins.jetbrains.com/plugin/14321-blackconnect).
+
+1. Open plugin configuration in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> BlackConnect`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> BlackConnect`
+
+1. In `Local Instance (shared between projects)` section:
+   1. Check `Start local blackd instance when plugin loads`.
+   1. Press the `Detect` button near `Path` input. The plugin should detect the `blackd`
+      executable.
+
+1. In `Trigger Settings` section check `Trigger on code reformat` to enable code
+   reformatting with _Black_.
+
+1. Format the currently opened file by selecting `Code -> Reformat Code` or using a
+   shortcut.
+
+1. Optionally, to run _Black_ on every file save:
+   - In `Trigger Settings` section of plugin configuration check
+     `Trigger when saving changed files`.
+
+### As external tool
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ where black
+   C:\Program Files\Python313\Scripts\black.exe  # possible location
+   ```
+
+   Note that if you are using a virtual environment detected by PyCharm, this is an
+   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
+1. Open External tools in PyCharm/IntelliJ IDEA
+
+   On macOS:
+
+   `PyCharm -> Preferences -> Tools -> External Tools`
+
+   On Windows / Linux / BSD:
+
+   `File -> Settings -> Tools -> External Tools`
+
+1. Click the + icon to add a new external tool with the following values:
+   - Name: Black
+   - Description: Black is the uncompromising Python code formatter.
+   - Program: \<install_location_from_step_2>
+   - Arguments: `"$FilePath$"`
+
+1. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+   - Alternatively, you can set a keyboard shortcut by navigating to
+     `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+
+### As file watcher
+
+1. Install `black`.
+
+   ```console
+   $ pip install black
+   ```
+
+1. Locate your `black` installation folder.
+
+   On macOS / Linux / BSD:
+
+   ```console
+   $ which black
+   /usr/local/bin/black  # possible location
+   ```
+
+   On Windows:
+
+   ```console
+   $ where black
+   C:\Program Files\Python313\Scripts\black.exe  # possible location
+   ```
+
+   Note that if you are using a virtual environment detected by PyCharm, this is an
+   unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+
+1. Make sure you have the
+   [File Watchers](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin
+   installed.
+1. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new
+   watcher:
+   - Name: Black
+   - File type: Python
+   - Scope: Project Files
+   - Program: \<install_location_from_step_2>
+   - Arguments: `$FilePath$`
+   - Output paths to refresh: `$FilePath$`
+   - Working directory: `$ProjectFileDir$`
+
+- In Advanced Options
+  - Uncheck "Auto-save edited files to trigger the watcher"
+  - Uncheck "Trigger the watcher on external changes"
+
+## Wing IDE
+
+Wing IDE supports `black` via **Preference Settings** for system wide settings and
+**Project Properties** for per-project or workspace specific settings, as explained in
+the Wing documentation on
+[Auto-Reformatting](https://wingware.com/doc/edit/auto-reformatting). The detailed
+procedure is:
+
+### Prerequisites
+
+- Wing IDE version 8.0+
+
+- Install `black`.
+
+  ```console
+  $ pip install black
+  ```
+
+- Make sure it runs from the command line, e.g.
+
+  ```console
+  $ black --help
+  ```
+
+### Preference Settings
+
+If you want Wing IDE to always reformat with `black` for every project, follow these
+steps:
+
+1. In menubar navigate to `Edit -> Preferences -> Editor -> Reformatting`.
+
+1. Set **Auto-Reformat** from `disable` (default) to `Line after edit` or
+   `Whole files before save`.
+
+1. Set **Reformatter** from `PEP8` (default) to `Black`.
+
+### Project Properties
+
+If you want to just reformat for a specific project and not intervene with Wing IDE
+global setting, follow these steps:
+
+1. In menubar navigate to `Project -> Project Properties -> Options`.
+
+1. Set **Auto-Reformat** from `Use Preferences setting` (default) to `Line after edit`
+   or `Whole files before save`.
+
+1. Set **Reformatter** from `Use Preferences setting` (default) to `Black`.
+
+## Vim
+
+### Official plugin
+
+Commands and shortcuts:
+
+- `:Black` to format the entire file (ranges not supported);
+  - you can optionally pass `target_version=<version>` with the same values as in the
+    command line.
+- `:BlackUpgrade` to upgrade _Black_ inside the virtualenv;
+- `:BlackVersion` to get the current version of _Black_ in use.
+
+Configuration:
+
+- `g:black_fast` (defaults to `0`)
+- `g:black_linelength` (defaults to `88`)
+- `g:black_skip_string_normalization` (defaults to `0`)
+- `g:black_skip_magic_trailing_comma` (defaults to `0`)
+- `g:black_virtualenv` (defaults to `~/.vim/black` or `~/.local/share/nvim/black`)
+- `g:black_use_virtualenv` (defaults to `1`)
+- `g:black_target_version` (defaults to `""`)
+- `g:black_quiet` (defaults to `0`)
+- `g:black_preview` (defaults to `0`)
+
+#### Installation
+
+This plugin **requires Vim 7.0+ built with Python 3.10+ support**. It needs Python 3.10
+to be able to run _Black_ inside the Vim process which is much faster than calling an
+external command.
+
+##### `vim-plug`
+
+To install with [vim-plug](https://junegunn.github.io/vim-plug/):
+
+_Black_'s `stable` branch tracks official version updates, and can be used to simply
+follow the most recent stable version.
+
+```vim
+Plug 'psf/black', { 'branch': 'stable' }
+```
+
+Another option which is a bit more explicit and offers more control is to use
+`vim-plug`'s `tag` option with a shell wildcard. This will resolve to the latest tag
+which matches the given pattern.
+
+The following matches all stable versions (see the
+[Release Process](../contributing/release_process.md) section for documentation of
+version scheme used by Black):
+
+```vim
+Plug 'psf/black', { 'tag': '*.*.*' }
+```
+
+and the following demonstrates pinning to a specific year's stable style (2026 in this
+case):
+
+```vim
+Plug 'psf/black', { 'tag': '26.*.*' }
+```
+
+##### Vundle
+
+or with [Vundle](https://github.com/VundleVim/Vundle.vim):
+
+```vim
+Plugin 'psf/black'
+```
+
+and execute the following in a terminal:
+
+```console
+$ cd ~/.vim/bundle/black
+$ git checkout origin/stable -b stable
+```
+
+##### Arch Linux
+
+On Arch Linux, the plugin is shipped with the
+[`python-black`](https://archlinux.org/packages/extra/any/python-black/) package, so you
+can start using it in Vim after install with no additional setup.
+
+##### Vim 8 Native Plugin Management
+
+or you can copy the plugin files from
+[plugin/black.vim](https://github.com/psf/black/blob/stable/plugin/black.vim) and
+[autoload/black.vim](https://github.com/psf/black/blob/stable/autoload/black.vim).
+
+```sh
+mkdir -p ~/.vim/pack/python/start/black/plugin
+mkdir -p ~/.vim/pack/python/start/black/autoload
+curl https://raw.githubusercontent.com/psf/black/stable/plugin/black.vim -o ~/.vim/pack/python/start/black/plugin/black.vim
+curl https://raw.githubusercontent.com/psf/black/stable/autoload/black.vim -o ~/.vim/pack/python/start/black/autoload/black.vim
+```
+
+Let me know if this requires any changes to work with Vim 8's builtin `packadd`, or
+Pathogen, and so on.
+
+#### Usage
+
+On first run, the plugin creates its own virtualenv using the right Python version and
+automatically installs _Black_. You can upgrade it later by calling `:BlackUpgrade` and
+restarting Vim.
+
+If you need to do anything special to make your virtualenv work and install _Black_ (for
+example you want to run a version from main), create a virtualenv manually and point
+`g:black_virtualenv` to it. The plugin will use it.
+
+If you would prefer to use the system installation of _Black_ rather than a virtualenv,
+then add this to your vimrc:
+
+```vim
+let g:black_use_virtualenv = 0
+```
+
+Note that the `:BlackUpgrade` command is only usable and useful with a virtualenv, so
+when the virtualenv is not in use, `:BlackUpgrade` is disabled. If you need to upgrade
+the system installation of _Black_, then use your system package manager or pip--
+whatever tool you used to install _Black_ originally.
+
+To run _Black_ on save, add the following lines to `.vimrc` or `init.vim`:
+
+```vim
+augroup black_on_save
+  autocmd!
+  autocmd BufWritePre *.py Black
+augroup end
+```
+
+To run _Black_ on a key press (e.g. F9 below), add this:
+
+```vim
+nnoremap <F9> :Black<CR>
+```
+
+### With ALE
+
+1. Install [`ale`](https://github.com/dense-analysis/ale)
+
+1. Install `black`
+
+1. Add this to your vimrc:
+
+   ```vim
+   let g:ale_fixers = {}
+   let g:ale_fixers.python = ['black']
+   ```
+
+## Neovim
+
+### Via conform.nvim
+
+[conform.nvim](https://github.com/stevearc/conform.nvim) is a lightweight formatter
+plugin for Neovim. It supports _Black_ out of the box as long as `black` is available in
+your `PATH`.
+
+1. Install `black` (e.g. `pip install black` or `pipx install black`)
+
+1. Install `conform.nvim` using your plugin manager and add the following to your Neovim
+   configuration:
+
+   ```lua
+   require("conform").setup({
+     formatters_by_ft = {
+       python = { "black" },
+     },
+   })
+   ```
+
+1. To format on save, add:
+
+   ```lua
+   require("conform").setup({
+     formatters_by_ft = {
+       python = { "black" },
+     },
+     format_on_save = {
+       timeout_ms = 500,
+       lsp_format = "fallback",
+     },
+   })
+   ```
+
+### With ALE
+
+[ALE](https://github.com/dense-analysis/ale) supports both Vim and Neovim. See the
+[Vim section](#with-ale) above for setup instructions — the same configuration works for
+Neovim.
+
+### Simple command
+
+You can invoke _Black_ on the current file directly from Neovim without any plugins:
+
+```vim
+:!black %
+```
+
+To create a convenient `:Black` command, add this to your `init.lua`:
+
+```lua
+vim.api.nvim_create_user_command(
+  "Black",
+  function()
+    vim.cmd("!black " .. vim.fn.expand("%"))
+  end,
+  { nargs = 0 }
+)
+```
+
+## Gedit
+
+gedit is the default text editor of the GNOME, Unix like Operating Systems. Open gedit
+as
+
+```console
+$ gedit <file_name>
+```
+
+1. `Go to edit > preferences > plugins`
+1. Search for `external tools` and activate it.
+1. In `Tools menu -> Manage external tools`
+1. Add a new tool using `+` button.
+1. Copy the below content to the code window.
+
+```sh
+#!/bin/bash
+Name=$GEDIT_CURRENT_DOCUMENT_NAME
+black $Name
+```
+
+- Set a keyboard shortcut if you like, Ex. `ctrl-B`
+- Save: `Nothing`
+- Input: `Nothing`
+- Output: `Display in bottom pane` if you like.
+- Change the name of the tool if you like.
+
+Use your keyboard shortcut or `Tools -> External Tools` to use your new tool. When you
+close and reopen your File, _Black_ will be done with its job.
+
+## Visual Studio Code
+
+- Use the
+  [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+  ([instructions](https://code.visualstudio.com/docs/python/formatting)).
+
+- Alternatively the pre-release
+  [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter)
+  extension can be used which runs a [Language Server Protocol](https://langserver.org/)
+  server for Black. Formatting is much more responsive using this extension, **but the
+  minimum supported version of Black is 22.3.0**.
+
+## SublimeText
+
+Use [LSP](#python-lsp-server) with the
+[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin as documented
+below. This is the recommended approach for all versions of Sublime Text.
+
+```{note}
+The [sublack plugin](https://github.com/jgirardet/sublack) that was previously
+recommended here is no longer maintained (the repository has been archived).
+```
+
+## Python LSP Server
+
+If your editor supports the [Language Server Protocol](https://langserver.org/) (Atom,
+Sublime Text, Visual Studio Code and many more), you can use the
+[Python LSP Server](https://github.com/python-lsp/python-lsp-server) with the
+[python-lsp-black](https://github.com/python-lsp/python-lsp-black) plugin.
+
+## Gradle (the build tool)
+
+Use the [Spotless](https://plugins.gradle.org/plugin/com.diffplug.spotless) plugin.
+
+## Kakoune
+
+Add the following hook to your kakrc, then run _Black_ with `:format`.
+
+```
+hook global WinSetOption filetype=python %{
+    set-option window formatcmd 'black -q  -'
+}
+```
+
+## Thonny
+
+Use [Thonny-black-formatter](https://github.com/ettore-galli/thonny-black-formatter).

docs/integrations/github_actions.md

@@ -0,0 +1,110 @@
+# GitHub Actions integration
+
+You can use _Black_ within a GitHub Actions workflow without setting your own Python
+environment. Great for enforcing that your code matches the _Black_ code style.
+
+## Compatibility
+
+This action is known to support all GitHub-hosted runner OSes. In addition, only
+published versions of _Black_ are supported (i.e. whatever is available on PyPI).
+
+Finally, this action installs _Black_ with the `colorama` extra so the `--color` flag
+should work fine.
+
+## Usage
+
+Create a file named `.github/workflows/black.yml` inside your repository with:
+
+```yaml
+name: Lint
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: psf/black@stable
+```
+
+We recommend the use of the `@stable` tag, but per version tags also exist if you prefer
+that. Note that the action's version you select is independent of the version of _Black_
+the action will use.
+
+### Versions
+
+The version of _Black_ the action will use can be configured via `version` or read from
+the `pyproject.toml` file. The action defaults to the latest release available on PyPI.
+
+`version` can be any
+[valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
+or just the version number if you want an exact version.
+
+If you want to match versions covered by Black's
+[stability policy](labels/stability-policy), you can use the compatible release operator
+(`~=`):
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+    version: "~= 26.0"
+```
+
+To read the version from the `pyproject.toml` file instead, set `use_pyproject` to
+`true`. This will first look into the `tool.black.required-version` field, then the
+`dependency-groups` table, then the `project.dependencies` array and finally the
+`project.optional-dependencies` table. Note that this requires Python >= 3.11, so using
+the setup-python action may be required, for example:
+
+**Security note:** `use_pyproject` only accepts standard version specifiers for `black`
+(for example `==`, `~=`, `>=` and ranges like `>=25,<26`). Direct references such as
+`black @ https://...` are not supported. If your workflow runs on untrusted pull
+requests (for example from forks), prefer setting `with.version` explicitly.
+
+```yaml
+- uses: actions/setup-python@v6
+  with:
+    python-version: "3.13"
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+    use_pyproject: true
+```
+
+Only versions available from PyPI are supported, so no commit SHAs or branch names.
+
+### Jupyter Notebooks
+
+If you want to include Jupyter Notebooks, it can be enabled by setting `jupyter` to
+`true` (default is `false`):
+
+```yaml
+- uses: psf/black@stable
+  with:
+    jupyter: true
+```
+
+See the [Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for
+more details.
+
+### CLI Options
+
+You can also configure the arguments passed to _Black_ via `options` (defaults to
+`'--check --diff'`) and `src` (default is `'.'`). Please note that the
+[`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_
+finds files that need to be formatted.
+
+Here's an example configuration:
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--check --verbose"
+    src: "./src"
+    jupyter: true
+    version: "21.5b1"
+```

docs/integrations/index.md

@@ -0,0 +1,33 @@
+# Integrations
+
+```{toctree}
+---
+hidden:
+---
+
+editors
+github_actions
+source_version_control
+doctest_formatting
+```
+
+_Black_ can be integrated into many environments, providing a better and smoother
+experience. Documentation for integrating _Black_ with a tool can be found for the
+following areas:
+
+- {doc}`Editor / IDE <./editors>`
+- {doc}`GitHub Actions <./github_actions>`
+- {doc}`Source version control <./source_version_control>`
+- {doc}`Doctest formatting <./doctest_formatting>`
+
+Editors and tools not listed will require external contributions.
+
+Patches welcome! ✨ 🍰 ✨
+
+Any tool can pipe code through _Black_ using its stdio mode (just
+[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
+The formatted code will be returned on stdout (unless `--check` was passed). _Black_
+will still emit messages on stderr but that shouldn't affect your use case.
+
+This can be used for example with PyCharm's or IntelliJ's
+[File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).

docs/integrations/source_version_control.md

@@ -0,0 +1,102 @@
+# Version control integration
+
+Use [pre-commit](https://pre-commit.com/). Once you
+[have it installed](https://pre-commit.com/#install), add this to the
+`.pre-commit-config.yaml` in your repository:
+
+```yaml
+repos:
+  # Using this mirror lets us use mypyc-compiled black, which is about 2x faster
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.5.1
+    hooks:
+      - id: black
+        # It is recommended to specify the latest version of Python
+        # supported by your project here, or alternatively use
+        # pre-commit's default_language_version, see
+        # https://pre-commit.com/#top_level-default_language_version
+        language_version: python3.11
+```
+
+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].
+
+## Jupyter Notebooks
+
+There is an alternate hook `black-jupyter` that expands the targets of `black` to
+include Jupyter Notebooks. To use this hook, simply replace the hook's `id: black` with
+`id: black-jupyter` in the `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.5.1
+    hooks:
+      - id: black-jupyter
+        language_version: python3.11
+```
+
+```{note}
+The `black-jupyter` hook became available in version 21.8b0.
+```
+
+See the [Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for
+more details.
+
+## Excluding files with pre-commit
+
+When using pre-commit, there's an important distinction in how file exclusions work.
+Pre-commit passes files directly to Black via the command line, rather than letting
+Black discover files recursively. This means Black's `--exclude` option won't work as
+expected because it only applies to files discovered during recursive directory
+traversal.
+
+To exclude files when using pre-commit, you have two options:
+
+### Option 1: Use pre-commit's exclude (Recommended)
+
+Configure exclusions directly in `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.5.1
+    hooks:
+      - id: black
+        exclude: ^migrations/|^generated/
+```
+
+This is the recommended approach because pre-commit filters files before passing them to
+Black, avoiding unnecessary processing.
+
+### Option 2: Use Black's force-exclude in pyproject.toml
+
+Black's `force-exclude` configuration option excludes files even when they are passed
+explicitly as command-line arguments (which is how pre-commit invokes Black). Simply add
+the pattern to your `pyproject.toml`:
+
+```toml
+[tool.black]
+force-exclude = '''
+(
+  ^migrations/
+  | ^generated/
+)
+'''
+```
+
+Black automatically reads this configuration—no additional CLI arguments are needed in
+your `.pre-commit-config.yaml`.
+
+```{note}
+The `force-exclude` option was added in version 20.8b0 specifically to support
+workflows where files are passed directly via CLI, such as pre-commit hooks and
+editor plugins.
+```
+
+[pre-commit-mutable-rev]:
+  https://pre-commit.com/#using-the-latest-version-for-a-repository