Skip to content

Commit

Permalink
docs: Unify option descriptions between --help and the_basics.md (#…
Browse files Browse the repository at this point in the history 
…4076)
  • Loading branch information
@RedGuy12
RedGuy12 committed Dec 7, 2023
1 parent 50e287c commit 432d905
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 51 deletions.
45 changes: 24 additions & 21 deletions docs/usage_and_configuration/the_basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ are deliberately limited and rarely added.
Note that all command-line options listed above can also be configured using a
`pyproject.toml` file (more on that below).

#### `-h`, `--help`

Show available command-line options and exit.

#### `-c`, `--code`

Format the code passed in as a string.
Expand Down Expand Up @@ -109,6 +113,10 @@ useful when piping source on standard input.
When processing Jupyter Notebooks, add the given magic to the list of known python-
magics. Useful for formatting cells with custom python magics.

#### `-x, --skip-source-first-line`

Skip the first line of the source code.

#### `-S, --skip-string-normalization`

By default, _Black_ uses double quotes for all strings and normalizes string prefixes,
Expand All @@ -132,7 +140,7 @@ functionality in the next major release. Read more about

#### `--check`

Passing `--check` will make _Black_ exit with:
Don't write the files back, just return the status. _Black_ will exit with:

- code 0 if nothing would change;
- code 1 if some files would be reformatted; or
Expand Down Expand Up @@ -162,8 +170,8 @@ $ echo $?

#### `--diff`

Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
would've made. They are printed to stdout so capturing them is simple.
Don't write the files back, just output a diff to indicate what changes _Black_ would've
made. They are printed to stdout so capturing them is simple.

If you'd like colored diffs, you can enable them with `--color`.

Expand All @@ -179,6 +187,10 @@ All done! ✨ 🍰 ✨
1 file would be reformatted.
```

#### `--color` / `--no-color`

Show (or do not show) colored diff. Only applies when `--diff` is given.

### `--line-ranges`

When specified, _Black_ will try its best to only format these lines.
Expand All @@ -202,10 +214,6 @@ extra lines outside of the ranges when ther are unformatted lines with the exact
content. It also disables _Black_'s formatting stability check in `--safe` mode.
```

#### `--color` / `--no-color`

Show (or do not show) colored diff. Only applies when `--diff` is given.

#### `--fast` / `--safe`

By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
Expand Down Expand Up @@ -256,7 +264,7 @@ instead of overriding them.
#### `--force-exclude`

Like `--exclude`, but files and directories matching this regex will be excluded even
when they are passed explicitly as arguments. This is useful when invoking _Black_
when they are passed explicitly as arguments. This is useful when invoking Black
programmatically on changed files, such as in a pre-commit hook or editor plugin.

#### `--stdin-filename`
Expand All @@ -275,12 +283,12 @@ exclusions, including from `.gitignore` and command line options.

When _Black_ formats multiple files, it may use a process pool to speed up formatting.
This option controls the number of parallel workers. This can also be specified via the
`BLACK_NUM_WORKERS` environment variable.
`BLACK_NUM_WORKERS` environment variable. Defaults to the number of CPUs in the system.

#### `-q`, `--quiet`

Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output.
Error messages will still be emitted (which can silenced by `2>/dev/null`).
Stop emitting all non-critical output. Error messages will still be emitted (which can
silenced by `2>/dev/null`).

```console
$ black src/ -q
Expand All @@ -289,9 +297,9 @@ error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio

#### `-v`, `--verbose`

Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
were not changed or were ignored due to exclusion patterns. If _Black_ is using a
configuration file, a blue message detailing which one it is using will be emitted.
Emit messages about files that were not changed or were ignored due to exclusion
patterns. If _Black_ is using a configuration file, a message detailing which one it is
using will be emitted.

```console
$ black src/ -v
Expand Down Expand Up @@ -321,10 +329,6 @@ black, 23.11.0
Read configuration options from a configuration file. See
[below](#configuration-via-a-file) for more details on the configuration file.

#### `-h`, `--help`

Show available command-line options and exit.

### Environment variable options

_Black_ supports the following configuration via environment variables.
Expand Down Expand Up @@ -355,7 +359,7 @@ All done! ✨ 🍰 ✨
use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
option on some editors that rely on using stdin.

You can also pass code as a string using the `-c` / `--code` option.
You can also pass code as a string using the `--code` option.

### Writeback and reporting

Expand Down Expand Up @@ -435,8 +439,7 @@ refers to the path to your home directory. On Windows, this will be something li
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.
If you're running with `--verbose`, you will see a message if a file was found and used.

Please note `blackd` will not use `pyproject.toml` configuration.

Expand Down
75 changes: 45 additions & 30 deletions src/black/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -235,25 +235,26 @@ def validate_regex(
callback=target_version_option_callback,
multiple=True,
help=(
"Python versions that should be supported by Black's output. By default, Black"
" will try to infer this from the project metadata in pyproject.toml. If this"
" does not yield conclusive results, Black will use per-file auto-detection."
"Python versions that should be supported by Black's output. You should"
" include all versions that your code supports. By default, Black will infer"
" target versions from the project metadata in pyproject.toml. If this does"
" not yield conclusive results, Black will use per-file auto-detection."
),
)
@click.option(
"--pyi",
is_flag=True,
help=(
"Format all input files like typing stubs regardless of file extension (useful"
" when piping source on standard input)."
"Format all input files like typing stubs regardless of file extension. This"
" is useful when piping source on standard input."
),
)
@click.option(
"--ipynb",
is_flag=True,
help=(
"Format all input files like Jupyter Notebooks regardless of file extension "
"(useful when piping source on standard input)."
"Format all input files like Jupyter Notebooks regardless of file extension."
"This is useful when piping source on standard input."
),
)
@click.option(
Expand Down Expand Up @@ -310,38 +311,47 @@ def validate_regex(
@click.option(
"--diff",
is_flag=True,
help="Don't write the files back, just output a diff for each file on stdout.",
help=(
"Don't write the files back, just output a diff to indicate what changes"
" Black would've made. They are printed to stdout so capturing them is simple."
),
)
@click.option(
"--color/--no-color",
is_flag=True,
help="Show (or do not show) colored diff. Only applies when --diff is given.",
)
@click.option(
"--line-ranges",
multiple=True,
metavar="START-END",
help=(
"When specified, _Black_ will try its best to only format these lines. This"
"When specified, Black will try its best to only format these lines. This"
" option can be specified multiple times, and a union of the lines will be"
" formatted. Each range must be specified as two integers connected by a `-`:"
" `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and"
" inclusive on both ends."
),
default=(),
)
@click.option(
"--color/--no-color",
is_flag=True,
help="Show colored diff. Only applies when `--diff` is given.",
)
@click.option(
"--fast/--safe",
is_flag=True,
help="If --fast given, skip temporary sanity checks. [default: --safe]",
help=(
"By default, Black performs an AST safety check after formatting your code."
" The --fast flag turns off this check and the --safe flag explicitly enables"
" it. [default: --safe]"
),
)
@click.option(
"--required-version",
type=str,
help=(
"Require a specific version of Black to be running (useful for unifying results"
" across many environments e.g. with a pyproject.toml file). It can be"
" either a major version number or an exact version."
"Require a specific version of Black to be running. This is useful for"
" ensuring that all contributors to your project are using the same"
" version, because different versions of Black may format code a little"
" differently. This option can be set in a configuration file for consistent"
" results across environments."
),
)
@click.option(
Expand Down Expand Up @@ -371,18 +381,20 @@ def validate_regex(
type=str,
callback=validate_regex,
help=(
"Like --exclude, but files and directories matching this regex will be "
"excluded even when they are passed explicitly as arguments."
"Like --exclude, but files and directories matching this regex will be excluded"
" even when they are passed explicitly as arguments. This is useful when"
" invoking Black programmatically on changed files, such as in a pre-commit"
" hook or editor plugin."
),
)
@click.option(
"--stdin-filename",
type=str,
is_eager=True,
help=(
"The name of the file when passing it through stdin. Useful to make "
"sure Black will respect --force-exclude option on some "
"editors that rely on using stdin."
"The name of the file when passing it through stdin. Useful to make sure Black"
" will respect the --force-exclude option on some editors that rely on using"
" stdin."
),
)
@click.option(
Expand All @@ -405,26 +417,29 @@ def validate_regex(
type=click.IntRange(min=1),
default=None,
help=(
"Number of parallel workers [default: BLACK_NUM_WORKERS environment variable "
"or number of CPUs in the system]"
"When Black formats multiple files, it may use a process pool to speed up"
" formatting. This option controls the number of parallel workers. This can"
" also be specified via the BLACK_NUM_WORKERS environment variable. Defaults"
" to the number of CPUs in the system."
),
)
@click.option(
"-q",
"--quiet",
is_flag=True,
help=(
"Don't emit non-error messages to stderr. Errors are still emitted; silence"
" those with 2>/dev/null."
"Stop emitting all non-critical output. Error messages will still be emitted"
" (which can silenced by 2>/dev/null)."
),
)
@click.option(
"-v",
"--verbose",
is_flag=True,
help=(
"Also emit messages to stderr about files that were not changed or were ignored"
" due to exclusion patterns."
"Emit messages about files that were not changed or were ignored due to"
" exclusion patterns. If Black is using a configuration file, a message"
" detailing which one it is using will be emitted."
),
)
@click.version_option(
Expand Down Expand Up @@ -455,7 +470,7 @@ def validate_regex(
),
is_eager=True,
callback=read_pyproject_toml,
help="Read configuration from FILE path.",
help="Read configuration options from a configuration file.",
)
@click.pass_context
def main( # noqa: C901
Expand Down

0 comments on commit 432d905

Please sign in to comment.