Elaborate on what AST changes Black might perform

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index b19e6e5e0982630a2f35a54f5f2e11fe76ee5d70..41cea761df564c4efb9ca60d323deb5d6073ac9b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -103,8 +103,8 @@ Options:
                                   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
+                                  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.
 
@@ -119,22 +119,22 @@ Options:
 
   --include TEXT                  A regular expression that matches files and
                                   directories that should be included on
-                                  recursive searches.  An empty value means
+                                  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
+                                  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
+                                  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|\.svn|_bu
-                                  ild|buck-out|build|dist)/]
+                                  later. [default: /(\.direnv|\.eggs|\.git|\.
+                                  hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv
+                                  n|_build|buck-out|build|dist)/]
 
   --extend-exclude TEXT           Like --exclude, but adds additional files
                                   and directories on top of the excluded
@@ -237,9 +237,11 @@ is that **until the formatter becomes stable, you should expect some formatting
 change in the future**. That being said, no drastic stylistic changes are planned,
 mostly responses to bug reports.
 
-Also, as a temporary safety measure, _Black_ will check that the reformatted code still
-produces a valid AST that is equivalent to the original. This slows it down. If you're
-feeling confident, use `--fast`.
+Also, as a safety measure which slows down processing, _Black_ will check that the
+reformatted code still produces a valid AST that is effectively equivalent to the
+original (see the
+[Pragmatism](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
+section for details). If you're feeling confident, use `--fast`.
 
 ## The _Black_ code style
 
@@ -539,8 +541,8 @@ Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
 [Carl Meyer](mailto:carl@oddbird.net),
 [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com),
 [Mika Naylor](mailto:mail@autophagy.io),
-[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and
-[Cooper Lees](mailto:me@cooperlees.com).
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com),
+[Cooper Lees](mailto:me@cooperlees.com), and Richard Si.
 
 Multiple contributions by: