docs/usage_and_configuration/black_docker_image.md

   1 # Black Docker image
   2
   3 Official _Black_ Docker images are available on
   4 [Docker Hub](https://hub.docker.com/r/pyfound/black).
   5
   6 _Black_ images with the following tags are available:
   7
   8 - release numbers, e.g. `21.5b2`, `21.6b0`, `21.7b0` etc.\
   9   ℹ Recommended for users who want to use a particular version of _Black_.
  10 - `latest_release` - tag created when a new version of _Black_ is released.\
  11   ℹ Recommended for users who want to use released versions of _Black_. It maps to [the latest release](https://github.com/psf/black/releases/latest)
  12   of _Black_.
  13 - `latest_prerelease` - tag created when a new alpha (prerelease) version of _Black_ is
  14   released.\
  15   ℹ Recommended for users who want to preview or test alpha versions of _Black_. Note that
  16   the most recent release may be newer than any prerelease, because no prereleases are created
  17   before most releases.
  18 - `latest` - tag used for the newest image of _Black_.\
  19   ℹ Recommended for users who always want to use the latest version of _Black_, even before
  20   it is released.
  21
  22 There is one more tag used for _Black_ Docker images - `latest_non_release`. It is
  23 created for all unreleased
  24 [commits on the `main` branch](https://github.com/psf/black/commits/main). This tag is
  25 not meant to be used by external users.
  26
  27 ## Usage
  28
  29 A permanent container doesn't have to be created to use _Black_ as a Docker image. It's
  30 enough to run _Black_ commands for the chosen image denoted as `:tag`. In the below
  31 examples, the `latest_release` tag is used. If `:tag` is omitted, the `latest` tag will
  32 be used.
  33
  34 More about _Black_ usage can be found in
  35 [Usage and Configuration: The basics](./the_basics.md).
  36
  37 ### Check Black version
  38
  39 ```console
  40 $ docker run --rm pyfound/black:latest_release black --version
  41 ```
  42
  43 ### Check code
  44
  45 ```console
  46 $ docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check .
  47 ```
  48
  49 _Remark_: besides [regular _Black_ exit codes](./the_basics.md) returned by `--check`
  50 option, [Docker exit codes](https://docs.docker.com/engine/reference/run/#exit-status)
  51 should also be considered.