]>
git.madduck.net Git - etc/vim.git/blobdiff - docs/usage_and_configuration/the_basics.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:
_Black_ is a well-behaved Unix-style command-line tool:
_Black_ is a well-behaved Unix-style command-line tool:
-- it does nothing if no sources are passed to i t;
+- it does nothing if it finds no sources to forma t;
- it will read from standard input and write to standard output if `-` is used as the
filename;
- it only outputs messages to users on standard error;
- it will read from standard input and write to standard output if `-` is used as the
filename;
- it only outputs messages to users on standard error;
-- exits with code 0 unless an internal error occurred (or `--check` was used) .
+- exits with code 0 unless an internal error occurred or a CLI option prompted it .
-_Black_ has quite a few knobs these days, although _Black_ is opinionated so style
-configuration options are deliberately limited and rarely added. You can list them by
-running `black --help` .
+The CLI options of _Black_ can be displayed by expanding the view below or by running
+`black --help`. While _Black_ has quite a few knobs these days, it is still opinionated
+so style options are deliberately limited and rarely added .
-<summary>Help output </summary>
+<summary>CLI reference </summary>
```{program-output} black --help
```{program-output} black --help
print("hello, world")
```
print("hello, world")
```
-```{warning}
---check, --diff, and --safe / --fast have no effect when using -c / --code. Safety
-checks normally turned on by default that verify _Black_'s output are disabled as well.
-This is a bug which we intend to fix eventually. More details can be found in this [bug
-report](https://github.com/psf/black/issues/2104).
-```
-
### Writeback and reporting
By default _Black_ reformats the files given and/or found in place. Sometimes you need
### Writeback and reporting
By default _Black_ reformats the files given and/or found in place. Sometimes you need
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
```
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
```
You can check the version of _Black_ you have installed using the `--version` flag.
```console
$ black --version
You can check the version of _Black_ you have installed using the `--version` flag.
```console
$ black --version
+An option to require a specific version to be running is also provided.
+
+```console
+$ black --required-version 21.9b0 -c "format = 'this'"
+format = "this"
+$ black --required-version 31.5b2 -c "still = 'beta?!'"
+Oh no! 💥 💔 💥 The required version does not match the running version!
+```
+
+This is useful for example when running _Black_ in multiple environments that haven't
+necessarily installed the correct version. This option can be set in a configuration
+file for consistent results across environments.
+
## Configuration via a file
_Black_ is able to read project-specific default values for its command line options
## Configuration via a file
_Black_ is able to read project-specific default values for its command line options
[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
[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://python-poetry.org/) or
-[Flit](https://flit.readthedocs.io/en/latest/) it can fully replace the need for
-`setup.py` and `setup.cfg` files.
+of tools like [Poetry](https://python-poetry.org/),
+[Flit](https://flit.readthedocs.io/en/latest/), or
+[Hatch](https://hatch.pypa.io/latest/) it can fully replace the need for `setup.py` and
+`setup.cfg` files.
### Where _Black_ looks for the file
### Where _Black_ looks for the file
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
+# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# 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)
+(
+ ^/foo.py # exclude a file named foo.py in the root of the project
+ | .*_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project
+)
projects / etc / vim.git / blobdiff