X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/97b8496d67741a10f30eefbb3d6c97a0e541fba4..b39999da7f451c285befac217f1f9a685774b34d:/README.md?ds=sidebyside diff --git a/README.md b/README.md index 178f763..41cea76 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,9 @@ _Contents:_ **[Installation and usage](#installation-and-usage)** | ### Installation -_Black_ can be installed by running `pip install black`. It requires Python 3.6.0+ to -run but you can reformat Python 2 code with it, too. +_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to +run. If you want to format Python 2 code as well, install with +`pip install black[python2]`. #### Install from GitHub @@ -102,8 +103,8 @@ Options: split lines. --check Don't write the files back, just return the - status. Return code 0 means nothing would - change. Return code 1 means some files + 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. @@ -118,28 +119,34 @@ Options: --include TEXT A regular expression that matches files and directories that should be included on - recursive searches. An empty value means + 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 + 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 + 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: /(\.direnv|\.eggs|\.git|\. - hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_bu - ild|buck-out|build|dist)/] + later. [default: /(\.direnv|\.eggs|\.git|\. + hg|\.mypy_cache|\.nox|\.tox|\.venv|venv|\.sv + n|_build|buck-out|build|dist)/] + + --extend-exclude TEXT Like --exclude, but adds additional files + and directories on top of the excluded + ones (useful if you simply want to add to + the default). --force-exclude TEXT Like --exclude, but files and directories matching this regex will be excluded even when they are passed explicitly as arguments. + --stdin-filename TEXT The name of the file when passing it through stdin. Useful to make sure Black will respect --force-exclude option on some @@ -151,7 +158,7 @@ Options: -v, --verbose Also emit messages to stderr about files that were not changed or were ignored due to - --exclude=. + exclusion patterns. --version Show the version and exit. --config FILE Read configuration from FILE path. @@ -230,9 +237,11 @@ is that **until the formatter becomes stable, you should expect some formatting change in the future**. That being said, no drastic stylistic changes are planned, mostly responses to bug reports. -Also, as a temporary safety measure, _Black_ will check that the reformatted code still -produces a valid AST that is equivalent to the original. This slows it down. If you're -feeling confident, use `--fast`. +Also, as a safety measure which slows down processing, _Black_ will check that the +reformatted code still produces a valid AST that is effectively equivalent to the +original (see the +[Pragmatism](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism) +section for details). If you're feeling confident, use `--fast`. ## The _Black_ code style @@ -263,7 +272,7 @@ above. What seems like a bug might be intended behaviour. _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. +`--include` and `--exclude`/`--extend-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. @@ -286,6 +295,20 @@ parent directories. It stops looking when it finds the file, or a `.git` directo If you're formatting standard input, _Black_ will look for configuration starting from the current working directory. +You can use a "global" configuration, stored in a specific location in your home +directory. This will be used as a fallback configuration, that is, it will be used if +and only if _Black_ doesn't find any configuration as mentioned above. Depending on your +operating system, this configuration file should be stored as: + +- Windows: `~\.black` +- Unix-like (Linux, MacOS, etc.): `$XDG_CONFIG_HOME/black` (`~/.config/black` if the + `XDG_CONFIG_HOME` environment variable is not set) + +Note that these are paths to the TOML file itself (meaning that they shouldn't be named +as `pyproject.toml`), not directories where you store the configuration. Here, `~` +refers to the path to your home directory. On Windows, this will be something like +`C:\\Users\UserName`. + 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. @@ -313,25 +336,10 @@ expressions by Black. Use `[ ]` to denote a significant space character. line-length = 88 target-version = ['py37'] include = '\.pyi?$' -exclude = ''' +extend-exclude = ''' # A regex preceded with ^/ will apply only to files and directories # in the root of the project. -^/( - ( - \.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 -) +^/foo.py # exclude a file named foo.py in the root of the project (in addition to the defaults) ''' ``` @@ -533,8 +541,8 @@ 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), -[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), and -[Cooper Lees](mailto:me@cooperlees.com). +[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com), +[Cooper Lees](mailto:me@cooperlees.com), and Richard Si. Multiple contributions by: @@ -616,6 +624,7 @@ Multiple contributions by: - [Joseph Larson](mailto:larson.joseph@gmail.com) - [Josh Bode](mailto:joshbode@fastmail.com) - [Josh Holland](mailto:anowlcalledjosh@gmail.com) +- [Joshua Cannon](mailto:joshdcannon@gmail.com) - [José Padilla](mailto:jpadilla@webapplicate.com) - [Juan Luis Cano Rodríguez](mailto:hello@juanlu.space) - [kaiix](mailto:kvn.hou@gmail.com)