]> git.madduck.net Git - etc/vim.git/blobdiff - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Remove deprecated license_file from setup.cfg (#825)
[etc/vim.git] / README.md
index 831401b3d256d8af2b6d002b619c4ef1e52e7771..add92855512bb8751dbf12e16c45f4cb519d7353 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,13 +1,14 @@
-![Black Logo](https://raw.githubusercontent.com/ambv/black/master/docs/_static/logo2-readme.png)
+![Black Logo](https://raw.githubusercontent.com/python/black/master/docs/_static/logo2-readme.png)
 <h2 align="center">The Uncompromising Code Formatter</h2>
 
 <p align="center">
-<a href="https://travis-ci.org/ambv/black"><img alt="Build Status" src="https://travis-ci.org/ambv/black.svg?branch=master"></a>
+<a href="https://travis-ci.org/python/black"><img alt="Build Status" src="https://travis-ci.org/python/black.svg?branch=master"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
-<a href="https://coveralls.io/github/ambv/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/ambv/black/badge.svg?branch=master"></a>
-<a href="https://github.com/ambv/black/blob/master/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
-<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
-<a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+<a href="https://coveralls.io/github/python/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/python/black/badge.svg?branch=master"></a>
+<a href="https://github.com/python/black/blob/master/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
+<a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
+<a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
+<a href="https://github.com/python/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
 > “Any color you like.”
@@ -26,17 +27,19 @@ content instead.
 *Black* makes code review faster by producing the smallest diffs
 possible.
 
+Try it out now using the [Black Playground](https://black.now.sh).
+
 ---
 
 *Contents:* **[Installation and usage](#installation-and-usage)** |
-**[The *Black* code style](#the-black-code-style)** |
-**[pyproject.toml](#pyproject.toml)** |
+**[Code style](#the-black-code-style)** |
+**[pyproject.toml](#pyprojecttoml)** |
 **[Editor integration](#editor-integration)** |
+**[blackd](#blackd)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
-**[License](#license)** |
 **[Contributing](#contributing-to-black)** |
 **[Change Log](#change-log)** |
 **[Authors](#authors)**
@@ -68,44 +71,58 @@ black {source_file_or_directory}
 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).
+  -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]
+  --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).
   -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 there was an
-                              internal error.
-  --diff                      Don't write the files back, just output a diff
-                              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.
-  -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.
-  --config PATH               Read configuration from PATH.
-  --help                      Show this message and exit.
+                                  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
+                                  there was an internal error.
+  --diff                          Don't write the files back, just output a
+                                  diff 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.  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: /(\.eggs|\.git|\.hg|\.mypy
+                                  _cache|\.nox|\.tox|\.venv|_build|buck-
+                                  out|build|dist)/]
+  -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
+                                  --exclude=.
+  --version                       Show the version and exit.
+  --config PATH                   Read configuration from PATH.
+  -h, --help                      Show this message and exit.
 ```
 
 *Black* is a well-behaved Unix-style command-line tool:
@@ -138,7 +155,8 @@ original.  This slows it down.  If you're feeling confident, use
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
-blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
+blocks that start with `# fmt: off` and end with `# fmt: on`. `# fmt: on/off`
+have to be on the same level of indentation. It also
 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
@@ -172,12 +190,12 @@ brackets and put that in a separate indented line.
 ```py3
 # in:
 
-TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
+ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
 
 # out:
 
-TracebackException.from_exception(
-    exc, limit, lookup_lines, capture_locals
+ImportantClass.important_method(
+    exc, limit, lookup_lines, capture_locals, extra_argument
 )
 ```
 
@@ -191,7 +209,7 @@ separate lines.
 ```py3
 # in:
 
-def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
+def very_important_function(template: str, *variables, file: os.PathLike, engine: str, header: bool = True, debug: bool = False):
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
@@ -202,6 +220,8 @@ def very_important_function(
     template: str,
     *variables,
     file: os.PathLike,
+    engine: str,
+    header: bool = True,
     debug: bool = False,
 ):
     """Applies `variables` to the `template` and writes to `file`."""
@@ -232,13 +252,13 @@ the following configuration.
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0
-combine_as_imports=True
+use_parentheses=True
 line_length=88
 ```
 
 The equivalent command line is:
 ```
-$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --combine-as --line-width=88 [ file.py ]
+$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
 ```
 </details>
 
@@ -274,7 +294,8 @@ ignore = E501
 ```
 
 You'll find *Black*'s own .flake8 config file is configured like this.
-If you're curious about the reasoning behind B950, Bugbear's documentation
+If you're curious about the reasoning behind B950, 
+[Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
@@ -349,11 +370,11 @@ The main reason to standardize on a single form of quotes is aesthetics.
 Having one kind of quotes everywhere reduces reader distraction.
 It will also enable a future version of *Black* to merge consecutive
 string literals that ended up on the same line (see
-[#26](https://github.com/ambv/black/issues/26) for details).
+[#26](https://github.com/python/black/issues/26) for details).
 
 Why settle on double quotes?  They anticipate apostrophes in English
-text.  They match the docstring standard described in PEP 257.  An
-empty string in double quotes (`""`) is impossible to confuse with
+text.  They match the docstring standard described in [PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring).
+An empty string in double quotes (`""`) is impossible to confuse with
 a one double-quote regardless of fonts and syntax highlighting used.
 On top of this, double quotes for strings are consistent with C which
 Python interacts a lot with.
@@ -369,6 +390,13 @@ 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.
 
+### Numeric literals
+
+*Black* standardizes most numeric literals to use lowercase letters for the
+syntactic parts and uppercase letters for the digits themselves: `0xAB`
+instead of `0XAB` and `1e10` instead of `1E10`. Python 2 long literals are
+styled as `2L` instead of `2l` to avoid confusion between `l` and `1`.
+
 
 ### Line breaks & binary operators
 
@@ -528,6 +556,8 @@ other file.
 If you're running with `--verbose`, you will see a blue message if
 a file was found and used.
 
+Please note `blackd` will not use `pyproject.toml` configuration.
+
 
 ### Configuration format
 
@@ -547,24 +577,26 @@ to denote a significant space character.
 ```toml
 [tool.black]
 line-length = 88
-py36 = true
+target-version = ['py37']
 include = '\.pyi?$'
 exclude = '''
-/(
-    \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | _build
-  | buck-out
-  | build
-  | dist
-
-  # The following are specific to Black, you probably don't want those.
-  | blib2to3
-  | tests/data
-)/
+
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+  )/
+  | foo.py           # also separately exclude a file named foo.py in
+                     # the root of the project
+)
 '''
 ```
 
@@ -588,7 +620,7 @@ configuration from different levels of the file hierarchy.
 Use [proofit404/blacken](https://github.com/proofit404/blacken).
 
 
-### PyCharm
+### PyCharm/IntelliJ IDEA
 
 1. Install `black`.
 
@@ -612,23 +644,43 @@ $ where black
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 
-3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
+3. Open External tools in PyCharm/IntelliJ IDEA
+
+  On macOS:
+  
+```PyCharm -> Preferences -> Tools -> External Tools```
+
+  On Windows / Linux / BSD:
+  
+```File -> Settings -> Tools -> External Tools```
 
 4. Click the + icon to add a new external tool with the following values:
     - Name: Black
     - Description: Black is the uncompromising Python code formatter.
     - Program: <install_location_from_step_2>
-    - Arguments: $FilePath$
+    - 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 -> External Tools -> External Tools - Black`.
+    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
+
+6. Optionally, run Black on every file save:
 
+    1. Make sure you have the [File Watcher](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin installed.
+    2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new watcher:
+        - Name: Black
+        - File type: Python
+        - Scope: Project Files
+        - Program: <install_location_from_step_2>
+        - Arguments: `$FilePath$`
+        - Output paths to refresh: `$FilePath$`
+        - Working directory: `$ProjectFileDir$`
+       - Uncheck "Auto-save edited files to trigger the watcher"
 
 ### Vim
 
 Commands and shortcuts:
 
-* `,=` or `:Black` to format the entire file (ranges not supported);
+* `:Black` to format the entire file (ranges not supported);
 * `:BlackUpgrade` to upgrade *Black* inside the virtualenv;
 * `:BlackVersion` to get the current version of *Black* inside the
   virtualenv.
@@ -642,16 +694,16 @@ Configuration:
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
-Plug 'ambv/black',
+Plug 'python/black'
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
-Plugin 'ambv/black'
+Plugin 'python/black'
 ```
 
-or you can copy the plugin from [plugin/black.vim](https://github.com/ambv/black/tree/master/plugin/black.vim).
+or you can copy the plugin from [plugin/black.vim](https://github.com/python/black/tree/master/plugin/black.vim).
 Let me know if this requires any changes to work with Vim 8's builtin
 `packadd`, or Pathogen, and so on.
 
@@ -671,7 +723,7 @@ The plugin will use it.
 To run *Black* on save, add the following line to `.vimrc` or `init.vim`:
 
 ```
-autocmd BufWritePost *.py execute ':Black'
+autocmd BufWritePre *.py execute ':Black'
 ```
 
 **How to get Vim with Python 3.6?**
@@ -685,8 +737,7 @@ to do this.
 ### Visual Studio Code
 
 Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
-([instructions](https://code.visualstudio.com/docs/python/editing#_formatting))
-or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+([instructions](https://code.visualstudio.com/docs/python/editing#_formatting)).
 
 
 ### SublimeText 3
@@ -694,15 +745,27 @@ or [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
-### IPython Notebook Magic
+### Jupyter Notebook Magic
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
 
+### Python Language Server
+
+If your editor supports the [Language Server Protocol](https://langserver.org/)
+(Atom, Sublime Text, Visual Studio Code and many more), you can use
+the [Python Language Server](https://github.com/palantir/python-language-server) with the
+[pyls-black](https://github.com/rupert/pyls-black) plugin.
+
+
+### Atom/Nuclide
+
+Use [python-black](https://atom.io/packages/python-black).
+
+
 ### Other editors
 
-Atom/Nuclide integration is planned by the author, others will
-require external contributions.
+Other editors will require external contributions.
 
 Patches welcome! ✨ 🍰 ✨
 
@@ -712,8 +775,79 @@ The formatted code will be returned on stdout (unless `--check` was
 passed).  *Black* will still emit messages on stderr but that shouldn't
 affect your use case.
 
-This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
+This can be used for example with PyCharm's or IntelliJ's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
+## blackd
+
+`blackd` is a small HTTP server that exposes *Black*'s functionality over
+a simple protocol. The main benefit of using it is to avoid paying the
+cost of starting up a new *Black* process every time you want to blacken
+a file.
+
+### Usage
+
+`blackd` is not packaged alongside *Black* by default because it has additional
+dependencies. You will need to do `pip install black[d]` to install it.
+
+You can start the server on the default port, binding only to the local interface
+by running `blackd`. You will see a single line mentioning the server's version,
+and the host and port it's listening on. `blackd` will then print an access log
+similar to most web servers on standard output, merged with any exception traces
+caused by invalid formatting requests.
+
+`blackd` provides even less options than *Black*. You can see them by running
+`blackd --help`:
+
+```text
+Usage: blackd [OPTIONS]
+
+Options:
+  --bind-host TEXT                Address to bind the server to.
+  --bind-port INTEGER             Port to listen on
+  --version                       Show the version and exit.
+  -h, --help                      Show this message and exit.
+```
+
+### Protocol
+
+`blackd` only accepts `POST` requests at the `/` path. The body of the request
+should contain the python source code to be formatted, encoded
+according to the `charset` field in the `Content-Type` request header. If no
+`charset` is specified, `blackd` assumes `UTF-8`.
+
+There are a few HTTP headers that control how the source is formatted. These
+correspond to command line flags for *Black*. There is one exception to this:
+`X-Protocol-Version` which if present, should have the value `1`, otherwise the
+request is rejected with `HTTP 501` (Not Implemented).
+
+The headers controlling how code is formatted are:
+
+ - `X-Line-Length`: corresponds to the `--line-length` command line flag.
+ - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
+    command line flag. If present and its value is not the empty string, no string
+    normalization will be performed.
+ - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as *Black* does when
+    passed the `--fast` command line flag.
+ - `X-Python-Variant`: if set to `pyi`, `blackd` will act as *Black* does when
+    passed the `--pyi` command line flag. Otherwise, its value must correspond to
+    a Python version or a set of comma-separated Python versions, optionally
+    prefixed with `py`. For example, to request code that is compatible
+    with Python 3.5 and 3.6, set the header to `py3.5,py3.6`.
+
+If any of these headers are set to invalid values, `blackd` returns a `HTTP 400`
+error response, mentioning the name of the problematic header in the message body.
+
+Apart from the above, `blackd` can produce the following response codes:
+
+ - `HTTP 204`: If the input is already well-formatted. The response body is
+       empty.
+ - `HTTP 200`: If formatting was needed on the input. The response body
+       contains the blackened Python code, and the `Content-Type` header is set
+       accordingly.
+ - `HTTP 400`: If the input contains a syntax error. Details of the error are
+       returned in the response body.
+ - `HTTP 500`: If there was any kind of error while trying to format the input.
+       The response body contains a textual representation of the error.
 
 ## Version control integration
 
@@ -722,7 +856,7 @@ installed](https://pre-commit.com/#install), add this to the
 `.pre-commit-config.yaml` in your repository:
 ```yaml
 repos:
--   repo: https://github.com/ambv/black
+-   repo: https://github.com/python/black
     rev: stable
     hooks:
     - id: black
@@ -748,9 +882,12 @@ location of the file depends on the *Black* version and the system on which *Bla
 is run. The file is non-portable. The standard location on common operating systems
 is:
 
-* Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.pickle`
-* macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.pickle`
-* Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.pickle`
+* Windows: `C:\\Users\<username>\AppData\Local\black\black\Cache\<version>\cache.<line-length>.<file-mode>.pickle`
+* macOS: `/Users/<username>/Library/Caches/black/<version>/cache.<line-length>.<file-mode>.pickle`
+* Linux: `/home/<username>/.cache/black/<version>/cache.<line-length>.<file-mode>.pickle`
+
+`file-mode` is an int flag that determines whether the file was formatted as 3.6+ only,
+as .pyi, and whether string normalization was omitted.
 
 
 ## Testimonials
@@ -759,7 +896,7 @@ is:
 
 > *Black* is opinionated so you don't have to be.
 
-**Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
+**Hynek Schlawack**, [creator of `attrs`](https://www.attrs.org/), core
 developer of Twisted and CPython:
 
 > An auto-formatter that doesn't suck is all I want for Xmas!
@@ -779,10 +916,16 @@ and [`pipenv`](https://docs.pipenv.org/):
 Use the badge in your project's README.md:
 
 ```markdown
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 ```
 
-Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+Using the badge in README.rst:
+```
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/python/black
+```
+
+Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 
 
 ## License
@@ -808,12 +951,142 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
+### 19.5b0
+
+* remove unnecessary parentheses around `yield` expressions (#834)
+
+* add parentheses around long tuples in unpacking assignments (#832)
+
+* don't produce invalid code for `from` ... `import` blocks with comments
+  (#829)
+
+* fix grammar selection (#765)
+
+* fix feature detection for trailing commas in function definitions and
+  call sites (#763)
+
+* fix bug that led *Black* format some code with a line length target of 1
+  (#762)
+
+### 19.3b0
+
+* new option `--target-version` to control which Python versions
+  *Black*-formatted code should target (#618)
+
+* deprecated `--py36` (use `--target-version=py36` instead) (#724)
+
+* *Black* no longer normalizes numeric literals to include `_` separators (#696)
+
+* long `del` statements are now split into multiple lines (#698)
+
+* type comments are no longer mangled in function signatures
+
+* improved performance of formatting deeply nested data structures (#509)
+
+* *Black* now properly formats multiple files in parallel on
+  Windows (#632)
+
+* *Black* now creates cache files atomically which allows it to be used
+  in parallel pipelines (like `xargs -P8`) (#673)
+
+* *Black* now correctly indents comments in files that were previously
+  formatted with tabs (#262)
+
+* `blackd` now supports CORS (#622)
+
+### 18.9b0
+
+* numeric literals are now formatted by *Black* (#452, #461, #464, #469):
+
+  * numeric literals are normalized to include `_` separators on Python 3.6+ code
+
+  * added `--skip-numeric-underscore-normalization` to disable the above behavior and
+    leave numeric underscores as they were in the input
+
+  * code with `_` in numeric literals is recognized as Python 3.6+
+
+  * most letters in numeric literals are lowercased (e.g., in `1e10`, `0x01`)
+
+  * hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
+
+* added `blackd`, see [its documentation](#blackd) for more info (#349)
+
+* adjacent string literals are now correctly split into multiple lines (#463)
+
+* trailing comma is now added to single imports that don't fit on a line (#250)
+
+* cache is now populated when `--check` is successful for a file which speeds up
+  consecutive checks of properly formatted unmodified files (#448)
+
+* whitespace at the beginning of the file is now removed (#399)
+
+* fixed mangling [pweave](http://mpastell.com/pweave/) and
+  [Spyder IDE](https://pythonhosted.org/spyder/) special comments (#532)
+
+* fixed unstable formatting when unpacking big tuples (#267)
+
+* fixed parsing of `__future__` imports with renames (#389)
+
+* fixed scope of `# fmt: off` when directly preceding `yield` and other nodes (#385)
+
+* fixed formatting of lambda expressions with default arguments (#468)
+
+* fixed ``async for`` statements: *Black* no longer breaks them into separate
+  lines (#372)
+
+* note: the Vim plugin stopped registering ``,=`` as a default chord as it turned out
+  to be a bad idea (#415)
+
+
+### 18.6b4
+
+* hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
+
+
+### 18.6b3
+
+* typing stub files (`.pyi`) now have blank lines added after constants (#340)
+
+* `# fmt: off` and `# fmt: on` are now much more dependable:
+
+  * they now work also within bracket pairs (#329)
+
+  * they now correctly work across function/class boundaries (#335)
+
+  * they now work when an indentation block starts with empty lines or misaligned
+    comments (#334)
+
+* made Click not fail on invalid environments; note that Click is right but the
+  likelihood we'll need to access non-ASCII file paths when dealing with Python source
+  code is low (#277)
+
+* fixed improper formatting of f-strings with quotes inside interpolated
+  expressions (#322)
+
+* fixed unnecessary slowdown when long list literals where found in a file
+
+* fixed unnecessary slowdown on AST nodes with very many siblings
+
+* fixed cannibalizing backslashes during string normalization
+
+* fixed a crash due to symbolic links pointing outside of the project directory (#338)
+
+
 ### 18.6b2
 
 * added `--config` (#65)
 
+* added `-h` equivalent to `--help` (#316)
+
 * fixed improper unmodified file caching when `-S` was used
 
+* fixed extra space in string unpacking (#305)
+
+* fixed formatting of empty triple quoted strings (#313)
+
+* fixed unnecessary slowdown in comment placement calculation on lines without
+  comments
+
 
 ### 18.6b1
 
@@ -1058,7 +1331,7 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 ### 18.3a2
 
 * changed positioning of binary operators to occur at beginning of lines
-  instead of at the end, following [a recent change to PEP8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
+  instead of at the end, following [a recent change to PEP 8](https://github.com/python/peps/commit/c59c4376ad233a62ca4b3a6060c81368bd21e85b)
   (#21)
 
 * ignore empty bracket pairs while splitting. This avoids very weirdly
@@ -1117,6 +1390,7 @@ Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
 
 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), and
 [Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).
 
@@ -1125,15 +1399,19 @@ Multiple contributions by:
 * [Artem Malyshev](mailto:proofit404@gmail.com)
 * [Christian Heimes](mailto:christian@python.org)
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
-* [Eli Treuherz](mailto:eli.treuherz@cgi.com)
+* [Eli Treuherz](mailto:eli@treuherz.com)
+* hauntsaninja
 * Hugo van Kemenade
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
-* [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
 * [Luka Sterbic](mailto:luka.sterbic@gmail.com)
 * [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
+* [Miroslav Shubernetskiy](mailto:miroslav@miki725.com)
+* [Neraste](mailto:neraste.herr10@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Peter Bengtsson](mailto:mail@peterbe.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
+* [Utsav Shah](mailto:ukshah2@illinois.edu)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
+* [Chuck Wooters](mailto:chuck.wooters@microsoft.com)