Add preview flag to Vim plugin (#3246)

[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 474ad669cd10992131bcc22f58248bd6dd2574e6..2dc2a14f91af3585948f133a4f7e77816017b80c 100644 (file)
--- 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:
 
 
 _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;
 - 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
 
 
 ## Usage
 


@@ -26,13 +26,13 @@ python -m black {source_file_or_directory}
 
 ### Command line options
 
 
 ### 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.

 
 <details>
 
 
 <details>
 

-<summary>Help output</summary>
+<summary>CLI reference</summary>

 
 ```{program-output} black --help
 
 
 ```{program-output} black --help
 


@@ -173,13 +173,13 @@ You can check the version of _Black_ you have installed using the `--version` fl
 
 ```console
 $ black --version
 
 ```console
 $ black --version

-black, version 21.5b0
+black, version 22.8.0

 ```
 
 An option to require a specific version to be running is also provided.
 
 ```console
 ```
 
 An option to require a specific version to be running is also provided.
 
 ```console

-$ black --required-version 21.5b2 -c "format = 'this'"
+$ 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!
 format = "this"
 $ black --required-version 31.5b2 -c "still = 'beta?!'"
 Oh no! 💥 💔 💥 The required version does not match the running version!


@@ -259,10 +259,14 @@ expressions by Black. Use `[ ]` to denote a significant space character.
 line-length = 88
 target-version = ['py37']
 include = '\.pyi?$'
 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.
 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
+)

 '''
 ```
 
 '''
 ```