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:

#455 Fix bug with tricky unicode symbols (#1047)
[etc/vim.git] / README.md
index 831401b3d256d8af2b6d002b619c4ef1e52e7771..90c169f4eeff30cd941132889a9e6fb1e64726b1 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/psf/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.com/psf/black"><img alt="Build Status" src="https://travis-ci.com/psf/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/psf/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/psf/black/badge.svg?branch=master"></a>
+<a href="https://github.com/psf/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/psf/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,21 @@ 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).
+Watch the [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
+
 ---
 
 *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)** |
+**[Used by](#used-by)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
-**[License](#license)** |
 **[Contributing](#contributing-to-black)** |
 **[Change Log](#change-log)** |
 **[Authors](#authors)**
@@ -68,44 +73,59 @@ 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).
+  -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]
+  --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:
@@ -119,7 +139,7 @@ Options:
 
 ### NOTE: This is a beta product
 
-*Black* is already successfully used by several projects, small and big.
+*Black* is already [successfully used](#used-by) by many projects, small and big.
 It also sports a decent test suite.  However, it is still very new.
 Things will probably be wonky for a while. This is made explicit by the
 "Beta" trove classifier, as well as by the "b" in the version number.
@@ -138,7 +158,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.
 
@@ -157,14 +178,14 @@ great.
 ```py3
 # in:
 
-l = [1,
+j = [1,
      2,
      3,
 ]
 
 # out:
 
-l = [1, 2, 3]
+j = [1, 2, 3]
 ```
 
 If not, *Black* will look at the contents of the first outer matching
@@ -172,12 +193,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 +212,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 +223,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 +255,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>
 
@@ -270,11 +293,12 @@ you are probably already using.  You'd do it like this:
 max-line-length = 80
 ...
 select = C,E,F,W,B,B950
-ignore = E501
+ignore = E501,W503,E203
 ```
 
 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 +373,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/psf/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 +393,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 +559,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 +580,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
+)
 '''
 ```
 
@@ -585,10 +620,11 @@ configuration from different levels of the file hierarchy.
 
 ### Emacs
 
-Use [proofit404/blacken](https://github.com/proofit404/blacken).
+Use [proofit404/blacken](https://github.com/proofit404/blacken) or
+[Elpy](https://github.com/jorgenschaefer/elpy).
 
 
-### PyCharm
+### PyCharm/IntelliJ IDEA
 
 1. Install `black`.
 
@@ -612,23 +648,75 @@ $ 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"
+
+
+
+### Wing IDE 
+
+Wing supports black via the OS Commands tool, as explained in the Wing documentation on [pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
 
+1. Install `black`.
+
+```console
+$ pip install black
+```
+
+2. Make sure it runs from the command line, e.g.
+
+```console
+$ black --help
+```
+
+3. In Wing IDE, activate the **OS Commands** panel  and define the command  **black** to execute black on the currently selected file:
+
+- Use the Tools -> OS Commands menu selection
+- click on **+** in **OS Commands** -> New: Command line..
+  - Title: black
+  - Command Line: black %s
+  - I/O Encoding: Use Default 
+  - Key Binding: F1
+  - [x] Raise OS Commands when executed
+  - [x] Auto-save files before execution
+  - [x] Line mode
+
+4. Select a file in the editor and press **F1** , or whatever key binding you selected in step 3, to reformat the file.
 
 ### 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 +730,16 @@ Configuration:
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
-Plug 'ambv/black',
+Plug 'psf/black'
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
-Plugin 'ambv/black'
+Plugin 'psf/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/psf/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 +759,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 +773,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 +781,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 +811,87 @@ 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.
+```
+
+There is no official blackd client tool (yet!). You can test that blackd is
+working using `curl`:
+
+```
+blackd --bind-port 9090 &  # or let blackd choose a port
+curl -s -XPOST "localhost:9090" -d "print('valid')"
+```
 
+### 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 +900,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/psf/black
     rev: stable
     hooks:
     - id: black
@@ -732,7 +910,7 @@ Then run `pre-commit install` and you're ready to go.
 
 Avoid using `args` in the hook.  Instead, store necessary configuration
 in `pyproject.toml` so that editors and command-line usage of Black all
-behave consistently for your project.  See *Black*'s own `pyproject.toml`
+behave consistently for your project.  See *Black*'s own [pyproject.toml](/pyproject.toml)
 for an example.
 
 If you're already using Python 3.7, switch the `language_version`
@@ -748,9 +926,26 @@ 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.
+
+To override the location of these files on macOS or Linux, set the environment variable
+`XDG_CACHE_HOME` to your preferred location. For example, if you want to put the cache in
+the directory you're running *Black* from, set `XDG_CACHE_HOME=.cache`. *Black* will then
+write the above files to `.cache/black/<version>/`.
+
+## Used by
+
+The following notable open-source projects trust *Black* with enforcing
+a consistent code style: pytest, tox, Pyramid, Django Channels, Hypothesis,
+attrs, SQLAlchemy, Poetry, PyPA applications (Warehouse, Pipenv, virtualenv),
+pandas, Pillow, every Datadog Agent Integration.
+
+Are we missing anyone?  Let us know.
 
 
 ## Testimonials
@@ -759,7 +954,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 +974,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/psf/black)
+```
+
+Using the badge in README.rst:
+```
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
 ```
 
-Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
 
 ## License
@@ -808,12 +1009,169 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
+### unreleased
+
+* added `black -c` as a way to format code passed from the command line
+  (#761)
+
+* --safe now works with Python 2 code (#840)
+
+* fixed grammar selection for Python 2-specific code (#765)
+
+* fixed feature detection for trailing commas in function definitions
+  and call sites (#763)
+
+* *Black* can now format async generators (#593)
+
+* *Black* no longer crashes on Windows machines with more than 61 cores
+  (#838)
+
+* *Black* no longer crashes on standalone comments prepended with
+  a backslash (#767)
+
+* *Black* no longer crashes on `from` ... `import` blocks with comments
+  (#829)
+
+* removed unnecessary parentheses around `yield` expressions (#834)
+
+* added parentheses around long tuples in unpacking assignments (#832)
+
+* fixed bug that led *Black* format some code with a line length target
+  of 1 (#762)
+
+* *Black* no longer introduces quotes in f-string subexpressions on string
+  boundaries (#863)
+
+* if *Black* puts parenthesis around a single expression, it moves comments
+  to the wrapped expression instead of after the brackets (#872)
+
+* *Black* is now able to format Python code that uses assignment expressions
+  (`:=` as described in PEP-572) (#935)
+
+* *Black* is now able to format Python code that uses positional-only
+  arguments (`/` as described in PEP-570) (#946)
+
+
+### 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 +1416,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,23 +1475,30 @@ 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).
 
 Multiple contributions by:
 * [Anthony Sottile](mailto:asottile@umich.edu)
 * [Artem Malyshev](mailto:proofit404@gmail.com)
+* [Benjamin Woodruff](mailto:github@benjam.info)
 * [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)
+* [Jason Fried](mailto:me@jasonfried.info)
 * [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)