chore: import upstream snapshot with attribution

2026-07-13 12:07:39 +08:00
commit d0aab9212a
460 changed files with 145411 additions and 0 deletions
@@ -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"
+```