<h2 align="center">The Uncompromising Code Formatter</h2>
<p align="center">
-<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://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Test/badge.svg"></a>
<a href="https://github.com/psf/black/actions"><img alt="Actions Status" src="https://github.com/psf/black/workflows/Primer/badge.svg"></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>
### Installation
_Black_ can be installed by running `pip install black`. It requires Python 3.6.2+ to
-run but you can reformat Python 2 code with it, too.
+run. If you want to format Python 2 code as well, install with
+`pip install black[python2]`.
#### Install from GitHub
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.
--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
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
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.
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
- uses: psf/black@stable
- with:
- args: ". --check"
```
-### Inputs
+You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
+follows:
-#### `black_args`
-
-**optional**: Black input arguments. Defaults to `. --check --diff`.
+```yaml
+- uses: psf/black@stable
+ with:
+ options: "--check --verbose"
+ src: "./src"
+```
## Ignoring unmodified files
[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:
projects / etc / vim.git / blobdiff