Add passing 3.11 CI by exempting blackd tests (#3234)

[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 6fd8769b591bd0949f25c9614589c8552035a937..4c358742674390e33834b64f8f2fb9db4d0d8941 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,104 +26,169 @@ 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

 
 

-```
-  Usage: black [OPTIONS] [SRC]...
-
-    The uncompromising code formatter.
-
-  Options:
-    -c, --code TEXT                 Format the code passed in as a string.
-    -l, --line-length INTEGER       How many characters per line to allow.
-                                    [default: 88]
-
-    -t, --target-version [py27|py33|py34|py35|py36|py37|py38|py39]
-                                    Python versions that should be supported by
-                                    Black's output. [default: per-file auto-
-                                    detection]
-
-    --pyi                           Format all input files like typing stubs
-                                    regardless of file extension (useful when
-                                    piping source on standard input).
-
-    -S, --skip-string-normalization
-                                    Don't normalize string quotes or prefixes.
-    -C, --skip-magic-trailing-comma
-                                    Don't use trailing commas as a reason to
-                                    split lines.
-
-    --check                         Don't write the files back, just return the
-                                    status. Return code 0 means nothing would
-                                    change. Return code 1 means some files
-                                    would be reformatted. Return code 123 means
-                                    there was an internal error.
-
-    --diff                          Don't write the files back, just output a
-                                    diff for each file on stdout.
-
-    --color / --no-color            Show colored diff. Only applies when
-                                    `--diff` is given.
-
-    --fast / --safe                 If --fast given, skip temporary sanity
-                                    checks. [default: --safe]
-
-    --include TEXT                  A regular expression that matches files and
-                                    directories that should be included on
-                                    recursive searches. An empty value means
-                                    all files are included regardless of the
-                                    name. Use forward slashes for directories
-                                    on all platforms (Windows, too). Exclusions
-                                    are calculated first, inclusions later.
-                                    [default: \.pyi?$]
-
-    --exclude TEXT                  A regular expression that matches files and
-                                    directories that should be excluded on
-                                    recursive searches. An empty value means no
-                                    paths are excluded. Use forward slashes for
-                                    directories on all platforms (Windows, too).
-                                    Exclusions are calculated first, inclusions
-                                    later.  [default: /(\.direnv|\.eggs|\.git|\.
-                                    hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.svn|_bu
-                                    ild|buck-out|build|dist)/]
-
-    --extend-exclude TEXT           Like --exclude, but adds additional files
-                                    and directories on top of the excluded
-                                    ones (useful if you simply want to add to
-                                    the default).
-
-    --force-exclude TEXT            Like --exclude, but files and directories
-                                    matching this regex will be excluded even
-                                    when they are passed explicitly as
-                                    arguments.
-
-
-    --stdin-filename TEXT           The name of the file when passing it through
-                                    stdin. Useful to make sure Black will
-                                    respect --force-exclude option on some
-                                    editors that rely on using stdin.
-
-    -q, --quiet                     Don't emit non-error messages to stderr.
-                                    Errors are still emitted; silence those with
-                                    2>/dev/null.
-
-    -v, --verbose                   Also emit messages to stderr about files
-                                    that were not changed or were ignored due to
-                                    exclusion patterns.
-
-    --version                       Show the version and exit.
-    --config FILE                   Read configuration from FILE path.
-    -h, --help                      Show this message and exit.

 ```
 
 </details>
 
 ```
 
 </details>
 

+### Code input alternatives
+
+#### Standard Input
+
+_Black_ supports formatting code via stdin, with the result being printed to stdout.
+Just let _Black_ know with `-` as the path.
+
+```console
+$ echo "print ( 'hello, world' )" | black -
+print("hello, world")
+reformatted -
+All done! ✨ 🍰 ✨
+1 file reformatted.
+```
+
+**Tip:** if you need _Black_ to treat stdin input as a file passed directly via the CLI,
+use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
+option on some editors that rely on using stdin.
+
+#### As a string
+
+You can also pass code as a string using the `-c` / `--code` option.
+
+```console
+$ black --code "print ( 'hello, world' )"
+print("hello, world")
+```
+
+### Writeback and reporting
+
+By default _Black_ reformats the files given and/or found in place. Sometimes you need
+_Black_ to just tell you what it _would_ do without actually rewriting the Python files.
+
+There's two variations to this mode that are independently enabled by their respective
+flags. Both variations can be enabled at once.
+
+#### Exit code
+
+Passing `--check` will make _Black_ exit with:
+
+- code 0 if nothing would change;
+- code 1 if some files would be reformatted; or
+- code 123 if there was an internal error
+
+```console
+$ black test.py --check
+All done! ✨ 🍰 ✨
+1 file would be left unchanged.
+$ echo $?
+0
+
+$ black test.py --check
+would reformat test.py
+Oh no! 💥 💔 💥
+1 file would be reformatted.
+$ echo $?
+1
+
+$ black test.py --check
+error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source.  Please report a bug on https://github.com/psf/black/issues.  This diff might be helpful: /tmp/blk_kjdr1oog.log
+Oh no! 💥 💔 💥
+1 file would fail to reformat.
+$ echo $?
+123
+```
+
+#### Diffs
+
+Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
+would've made. They are printed to stdout so capturing them is simple.
+
+If you'd like colored diffs, you can enable them with the `--color`.
+
+```console
+$ black test.py --diff
+--- test.py     2021-03-08 22:23:40.848954 +0000
++++ test.py     2021-03-08 22:23:47.126319 +0000
+@@ -1 +1 @@
+-print ( 'hello, world' )
++print("hello, world")
+would reformat test.py
+All done! ✨ 🍰 ✨
+1 file would be reformatted.
+```
+
+### Output verbosity
+
+_Black_ in general tries to produce the right amount of output, balancing between
+usefulness and conciseness. By default, _Black_ emits files modified and error messages,
+plus a short summary.
+
+```console
+$ black src/
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
+```
+
+Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
+were not changed or were ignored due to exclusion patterns. If _Black_ is using a
+configuration file, a blue message detailing which one it is using will be emitted.
+
+```console
+$ black src/ -v
+Using configuration from /tmp/pyproject.toml.
+src/blib2to3 ignored: matches the --extend-exclude regular expression
+src/_black_version.py wasn't modified on disk since last run.
+src/black/__main__.py wasn't modified on disk since last run.
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+reformatted src/black_primer/lib.py
+reformatted src/blackd/__init__.py
+reformatted src/black/__init__.py
+Oh no! 💥 💔 💥
+3 files reformatted, 2 files left unchanged, 1 file failed to reformat
+```
+
+Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critial output.
+Error messages will still be emitted (which can silenced by `2>/dev/null`).
+
+```console
+$ black src/ -q
+error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
+```
+
+### Versions
+
+You can check the version of _Black_ you have installed using the `--version` flag.
+
+```console
+$ black --version
+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
 ## Configuration via a file
 
 _Black_ is able to read project-specific default values for its command line options


@@ -194,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
+)

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