X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/26b92e66aca6124ba8761f690ec7ee18757411b7..489d00ed8f4fb90d5788609a474632ab5a16591f:/README.md?ds=sidebyside
diff --git a/README.md b/README.md
index 3f82dbd..831401b 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,10 @@
-
+
-
-
+
+
@@ -30,6 +30,7 @@ possible.
*Contents:* **[Installation and usage](#installation-and-usage)** |
**[The *Black* code style](#the-black-code-style)** |
+**[pyproject.toml](#pyproject.toml)** |
**[Editor integration](#editor-integration)** |
**[Version control integration](#version-control-integration)** |
**[Ignoring unmodified files](#ignoring-unmodified-files)** |
@@ -60,7 +61,7 @@ black {source_file_or_directory}
### Command line options
-Black doesn't provide many options. You can list them by running
+*Black* doesn't provide many options. You can list them by running
`black --help`:
```text
@@ -103,6 +104,7 @@ Options:
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.
```
@@ -487,6 +489,98 @@ a future version of the formatter:
* use `float` instead of `Union[int, float]`.
+## pyproject.toml
+
+*Black* is able to read project-specific default values for its
+command line options from a `pyproject.toml` file. This is
+especially useful for specifying custom `--include` and `--exclude`
+patterns for your project.
+
+**Pro-tip**: If you're asking yourself "Do I need to configure anything?"
+the answer is "No". *Black* is all about sensible defaults.
+
+
+### What on Earth is a `pyproject.toml` file?
+
+[PEP 518](https://www.python.org/dev/peps/pep-0518/) defines
+`pyproject.toml` as a configuration file to store build system
+requirements for Python projects. With the help of tools
+like [Poetry](https://poetry.eustace.io/) or
+[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the
+need for `setup.py` and `setup.cfg` files.
+
+
+### Where *Black* looks for the file
+
+By default *Black* looks for `pyproject.toml` starting from the common
+base directory of all files and directories passed on the command line.
+If it's not there, it looks in parent directories. It stops looking
+when it finds the file, or a `.git` directory, or a `.hg` directory,
+or the root of the file system, whichever comes first.
+
+If you're formatting standard input, *Black* will look for configuration
+starting from the current working directory.
+
+You can also explicitly specify the path to a particular file that you
+want with `--config`. In this situation *Black* will not look for any
+other file.
+
+If you're running with `--verbose`, you will see a blue message if
+a file was found and used.
+
+
+### Configuration format
+
+As the file extension suggests, `pyproject.toml` is a [TOML](https://github.com/toml-lang/toml) file. It contains separate
+sections for different tools. *Black* is using the `[tool.black]`
+section. The option keys are the same as long names of options on
+the command line.
+
+Note that you have to use single-quoted strings in TOML for regular
+expressions. It's the equivalent of r-strings in Python. Multiline
+strings are treated as verbose regular expressions by Black. Use `[ ]`
+to denote a significant space character.
+
+
+Example `pyproject.toml`
+
+```toml
+[tool.black]
+line-length = 88
+py36 = true
+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
+)/
+'''
+```
+
+
+
+### Lookup hierarchy
+
+Command-line options have defaults that you can see in `--help`.
+A `pyproject.toml` can override those defaults. Finally, options
+provided by the user on the command line override both.
+
+*Black* will only ever use one `pyproject.toml` file during an entire
+run. It doesn't look for multiple files, and doesn't compose
+configuration from different levels of the file hierarchy.
+
+
## Editor integration
### Emacs
@@ -542,6 +636,7 @@ Commands and shortcuts:
Configuration:
* `g:black_fast` (defaults to `0`)
* `g:black_linelength` (defaults to `88`)
+* `g:black_skip_string_normalization` (defaults to `0`)
* `g:black_virtualenv` (defaults to `~/.vim/black`)
To install with [vim-plug](https://github.com/junegunn/vim-plug):
@@ -589,7 +684,9 @@ to do this.
### Visual Studio Code
-Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
+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).
### SublimeText 3
@@ -610,7 +707,7 @@ require external contributions.
Patches welcome! ⨠ð° â¨
Any tool that can pipe code through *Black* using its stdio mode (just
-[use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
+[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
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.
@@ -629,23 +726,25 @@ repos:
rev: stable
hooks:
- id: black
- args: [--line-length=88, --safe]
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 `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.
+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`
+for an example.
+
+If you're already using Python 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.
## Ignoring unmodified files
*Black* remembers files it has already formatted, unless the `--diff` flag is used or
code is passed via standard input. This information is stored per-user. The exact
-location of the file depends on the black version and the system on which black
+location of the file depends on the *Black* version and the system on which *Black*
is run. The file is non-portable. The standard location on common operating systems
is:
@@ -658,7 +757,7 @@ is:
**Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
-> Black is opinionated so you don't have to be.
+> *Black* is opinionated so you don't have to be.
**Hynek Schlawack**, [creator of `attrs`](http://www.attrs.org/), core
developer of Twisted and CPython:
@@ -691,7 +790,7 @@ Looks like this: [.
## Change Log
+### 18.6b2
+
+* added `--config` (#65)
+
+* fixed improper unmodified file caching when `-S` was used
+
+
### 18.6b1
* hotfix: don't output human-facing information on stdout (#299)
@@ -840,10 +946,10 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
* generalized star expression handling, including double stars; this
fixes multiplication making expressions "unsafe" for trailing commas (#132)
-* Black no longer enforces putting empty lines behind control flow statements
+* *Black* no longer enforces putting empty lines behind control flow statements
(#90)
-* Black now splits imports like "Mode 3 + trailing comma" of isort (#127)
+* *Black* now splits imports like "Mode 3 + trailing comma" of isort (#127)
* fixed comment indentation when a standalone comment closes a block (#16, #32)
@@ -896,16 +1002,16 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
(#75)
* fixed handling of standalone comments within nested bracketed
- expressions; Black will no longer produce super long lines or put all
+ expressions; *Black* will no longer produce super long lines or put all
standalone comments at the end of the expression (#22)
* fixed 18.3a4 regression: don't crash and burn on empty lines with
trailing whitespace (#80)
* fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment
- would cause Black to not emit the rest of the file (#95)
+ would cause *Black* to not emit the rest of the file (#95)
-* when CTRL+C is pressed while formatting many files, Black no longer
+* when CTRL+C is pressed while formatting many files, *Black* no longer
freaks out with a flurry of asyncio-related exceptions
* only allow up to two empty lines on module level and only single empty
@@ -1027,22 +1133,7 @@ Multiple contributions by:
* [Luka Sterbic](mailto:luka.sterbic@gmail.com)
* [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
* [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
-* [Peter Bengtsson](mailto:peterbe@mozilla.com)
+* [Peter Bengtsson](mailto:mail@peterbe.com)
* [Stavros Korokithakis](mailto:hi@stavros.io)
* [Sunil Kapil](mailto:snlkapil@gmail.com)
* [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
-
----
-
-*Contents:*
-**[Installation and Usage](#installation-and-usage)** |
-**[The *Black* code style](#the-black-code-style)** |
-**[Editor integration](#editor-integration)** |
-**[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)**