X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/7c851dfa2c2a8f0bf4c529d7f6faa43798d04325..1b6de7b0a33b568f71ff86e0e5fef6d4c479c2b7:/docs/usage_and_configuration/the_basics.md?ds=inline diff --git a/docs/usage_and_configuration/the_basics.md b/docs/usage_and_configuration/the_basics.md index 0b2cd3b..4c35874 100644 --- a/docs/usage_and_configuration/the_basics.md +++ b/docs/usage_and_configuration/the_basics.md @@ -4,11 +4,11 @@ Foundational knowledge on using and configuring Black. _Black_ is a well-behaved Unix-style command-line tool: -- it does nothing if no sources are passed to it; +- it does nothing if it finds no sources to format; - it will read from standard input and write to standard output if `-` is used as the filename; - it only outputs messages to users on standard error; -- exits with code 0 unless an internal error occurred (or `--check` was used). +- exits with code 0 unless an internal error occurred or a CLI option prompted it. ## Usage @@ -26,13 +26,13 @@ python -m black {source_file_or_directory} ### Command line options -_Black_ has quite a few knobs these days, although _Black_ is opinionated so style -configuration options are deliberately limited and rarely added. You can list them by -running `black --help`. +The CLI options of _Black_ can be displayed by expanding the view below or by running +`black --help`. While _Black_ has quite a few knobs these days, it is still opinionated +so style options are deliberately limited and rarely added.
-Help output +CLI reference ```{program-output} black --help @@ -68,13 +68,6 @@ $ black --code "print ( 'hello, world' )" print("hello, world") ``` -```{warning} ---check, --diff, and --safe / --fast have no effect when using -c / --code. Safety -checks normally turned on by default that verify _Black_'s output are disabled as well. -This is a bug which we intend to fix eventually. More details can be found in this [bug -report](https://github.com/psf/black/issues/2104). -``` - ### Writeback and reporting By default _Black_ reformats the files given and/or found in place. Sometimes you need @@ -174,15 +167,28 @@ $ 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. ```console $ black --version -black, version 21.5b0 +black, version 22.6.0 ``` +An option to require a specific version to be running is also provided. + +```console +$ black --required-version 21.9b0 -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 @@ -253,10 +259,14 @@ expressions by Black. Use `[ ]` to denote a significant space character. line-length = 88 target-version = ['py37'] include = '\.pyi?$' +# 'extend-exclude' excludes files or directories in addition to the defaults extend-exclude = ''' # A regex preceded with ^/ will apply only to files and directories # in the root of the project. -^/foo.py # exclude a file named foo.py in the root of the project (in addition to the defaults) +( + ^/foo.py # exclude a file named foo.py in the root of the project + | .*_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project +) ''' ```