Add option to require a specific version to be running (#2300)

[etc/vim.git] / docs / usage_and_configuration / the_basics.md

diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md
index c5e17e5a5218f26344eaa2655630138468bba339..474ad669cd10992131bcc22f58248bd6dd2574e6 100644 (file)
--- a/docs/usage_and_configuration/the_basics.md
+++ b/docs/usage_and_configuration/the_basics.md
@@ -167,7 +167,7 @@ $ black src/ -q
 error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
 ```
 
-### Getting the version
+### Versions
 
 You can check the version of _Black_ you have installed using the `--version` flag.
 
@@ -176,6 +176,19 @@ $ black --version
 black, version 21.5b0
 ```
 
+An option to require a specific version to be running is also provided.
+
+```console
+$ black --required-version 21.5b2 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+This is useful for example when running _Black_ in multiple environments that haven't
+necessarily installed the correct version. This option can be set in a configuration
+file for consistent results across environments.
+
 ## Configuration via a file
 
 _Black_ is able to read project-specific default values for its command line options