Improve error messages from BlackRunner

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 4d7f5fdba6e367b7cc7ab50832aba9f7934b7f91..d0148b54017e7a8956c0cb7e0bd0bac979e8baa9 100644 (file)
--- a/README.md
+++ b/README.md
@@ -61,36 +61,41 @@ black {source_file_or_directory}
 _Black_ doesn't provide many options. You can list them by running `black --help`:
 
 ```text
 _Black_ doesn't provide many options. You can list them by running `black --help`:
 
 ```text

-black [OPTIONS] [SRC]...
+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]
 
 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]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
   -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]

-  --py36                          Allow using Python 3.6-only syntax on all
-                                  input files.  This will put trailing commas
-                                  in function signatures and calls also after
-                                  *args and **kwargs. Deprecated; use
-                                  --target-version instead. [default: per-file
-                                  auto-detection]
+

   --pyi                           Format all input files like typing stubs
                                   regardless of file extension (useful when
                                   piping source on standard input).
   --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.
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
   --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
+                                  would be reformatted. Return code 123 means

                                   there was an internal error.
                                   there was an internal error.

+

   --diff                          Don't write the files back, just output a
                                   diff for each file on stdout.
   --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]
   --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
   --include TEXT                  A regular expression that matches files and
                                   directories that should be included on
                                   recursive searches.  An empty value means


@@ -99,6 +104,7 @@ Options:
                                   on all platforms (Windows, too).  Exclusions
                                   are calculated first, inclusions later.
                                   [default: \.pyi?$]
                                   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
   --exclude TEXT                  A regular expression that matches files and
                                   directories that should be excluded on
                                   recursive searches.  An empty value means no


@@ -106,16 +112,23 @@ Options:
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later.  [default: /(\.eggs|\.git|\.hg|\.mypy
                                   directories on all platforms (Windows, too).
                                   Exclusions are calculated first, inclusions
                                   later.  [default: /(\.eggs|\.git|\.hg|\.mypy

-                                  _cache|\.nox|\.tox|\.venv|_build|buck-
+                                  _cache|\.nox|\.tox|\.venv|\.svn|_build|buck-

                                   out|build|dist)/]
                                   out|build|dist)/]

+
+  --force-exclude TEXT            Like --exclude, but files and directories
+                                  matching this regex will be excluded even
+                                  when they are passed explicitly as arguments
+

   -q, --quiet                     Don't emit non-error messages to stderr.
   -q, --quiet                     Don't emit non-error messages to stderr.

-                                  Errors are still emitted, silence those with
+                                  Errors are still emitted; silence those with

                                   2>/dev/null.
                                   2>/dev/null.

+

   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
                                   --exclude=.
   -v, --verbose                   Also emit messages to stderr about files
                                   that were not changed or were ignored due to
                                   --exclude=.

+

   --version                       Show the version and exit.
   --version                       Show the version and exit.

-  --config PATH                   Read configuration from PATH.
+  --config FILE                   Read configuration from PATH.

   -h, --help                      Show this message and exit.
 ```
 
   -h, --help                      Show this message and exit.
 ```
 


@@ -127,6 +140,16 @@ _Black_ is a well-behaved Unix-style command-line tool:
 - it only outputs messages to users on standard error;
 - exits with code 0 unless an internal error occurred (or `--check` was used).
 
 - it only outputs messages to users on standard error;
 - exits with code 0 unless an internal error occurred (or `--check` was used).
 

+### Using _Black_ with other tools
+
+While _Black_ enforces formatting that conforms to PEP 8, other tools may raise warnings
+about _Black_'s changes or will overwrite _Black_'s changes. A good example of this is
+[isort](https://pypi.org/p/isort). Since _Black_ is barely configurable, these tools
+should be configured to neither warn about nor overwrite _Black_'s changes.
+
+Actual details on _Black_ compatible configurations for various tools can be found in
+[compatible_configs](./docs/compatible_configs.md).
+

 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](#used-by) by many projects, small and big. It
 ### NOTE: This is a beta product
 
 _Black_ is already [successfully used](#used-by) by many projects, small and big. It


@@ -648,6 +671,9 @@ $ where black
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 

+Note that if you are using a virtual environment detected by PyCharm, this is an
+unneeded step. In this case the path to `black` is `$PyInterpreterDirectory$/black`.
+

 3. Open External tools in PyCharm/IntelliJ IDEA
 
 On macOS:
 3. Open External tools in PyCharm/IntelliJ IDEA
 
 On macOS:


@@ -985,6 +1011,8 @@ code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy
 Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
 Agent Integration, Home Assistant.
 
 Poetry, PyPA applications (Warehouse, Pipenv, virtualenv), pandas, Pillow, every Datadog
 Agent Integration, Home Assistant.
 

+The following organizations use _Black_: Dropbox.
+

 Are we missing anyone? Let us know.
 
 ## Testimonials
 Are we missing anyone? Let us know.
 
 ## Testimonials