Preserve line endings when formatting a file in place (#288)

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 17c67f71c85dd689fb42db5c1e61684d0a3e351f..beba56cc2ebff85a2ac7268e1aee841981ef7129 100644 (file)
--- a/README.md
+++ b/README.md
@@ -68,6 +68,15 @@ black [OPTIONS] [SRC]...
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
+  --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.  [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.
   --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
@@ -77,16 +86,22 @@ Options:
                               for each file on stdout.
   --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. On Windows, use forward
+                              slashes for directories.  [default: \.pyi?$]
+  --exclude TEXT              A regular expression that matches files and
+                              directories that should be excluded on
+                              recursive searches. On Windows, use forward
+                              slashes for directories.  [default:
+                              build/|buck-out/|dist/|_build/|\.git/|\.hg/|
+                              \.mypy_cache/|\.tox/|\.venv/]
   -q, --quiet                 Don't emit non-error messages to stderr. Errors
                               are still emitted, silence those with
                               2>/dev/null.
-   --pyi                      Consider all input files typing stubs regardless
-                              of file extension (useful when piping source on
-                              standard input).
-  --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.  [default: per-file auto-detection]
+  -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.
   --help                      Show this message and exit.
 ```
@@ -346,6 +361,12 @@ a bit easier than double quotes.  The latter requires use of the Shift
 key.  My recommendation here is to keep using whatever is faster to type
 and let *Black* handle the transformation.
 
+If you are adopting *Black* in a large project with pre-existing string
+conventions (like the popular ["single quotes for data, double quotes for
+human-readable strings"](https://stackoverflow.com/a/56190)), you can
+pass `--skip-string-normalization` on the command line.  This is meant as
+an adoption helper, avoid using this for new projects.
+
 
 ### Line breaks & binary operators
 
@@ -506,7 +527,7 @@ $ where black
     - Arguments: $FilePath$
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
-    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap`.
+    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
 
 
 ### Vim
@@ -609,13 +630,13 @@ repos:
     hooks:
     - id: black
       args: [--line-length=88, --safe]
-      python_version: python3.6
+      language_version: python3.6
 ```
 Then run `pre-commit install` and you're ready to go.
 
 `args` in the above config is optional but shows you how you can change
 the line length if you really need to.  If you're already using Python
-3.7, switch the `python_version` accordingly. Finally, `stable` is a tag
+3.7, switch the `language_version` accordingly. Finally, `stable` is a tag
 that is pinned to the latest release on PyPI.  If you'd rather run on
 master, this is also an option.
 
@@ -688,7 +709,21 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
-### 18.5b1 (unreleased)
+### 18.6b0
+
+* added `--include` and `--exclude` (#270)
+
+* added `--skip-string-normalization` (#118)
+
+* added `--verbose` (#283)
+
+* fixed stdin handling not working correctly if an old version of Click was
+  used (#276)
+
+* *Black* now preserves line endings when formatting a file in place (#258)
+
+
+### 18.5b1
 
 * added `--pyi` (#249)
 
@@ -715,6 +750,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * fixed extra empty line between a class declaration and the first
   method if no class docstring or fields are present (#219)
 
+* fixed extra empty line between a function signature and an inner
+  function or inner class (#196)
+
 
 ### 18.5b0
 
@@ -976,6 +1014,7 @@ Multiple contributions by:
 * [Luka Sterbic](mailto:luka.sterbic@gmail.com)
 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
+* [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)