docs: Unify option descriptions between --help and the_basics.md (#4076)

Author: cobaltt7

docs/usage_and_configuration/the_basics.md

@@ -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.
@@ -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,
@@ -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
@@ -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`.
 
@@ -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.
@@ -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
@@ -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`
@@ -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
@@ -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
@@ -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.
@@ -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
 
@@ -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.
 

src/black/__init__.py

@@ -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(
@@ -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(
@@ -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(
@@ -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(
@@ -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