Skip to content

Make the documented -v example match what black actually prints - #5560

Merged
JelleZijlstra merged 1 commit into
psf:mainfrom
ump45nose:docs-verbose-example-output
Oct 18, 2026
Merged

JelleZijlstra merged 1 commit into
psf:mainfrom
ump45nose:docs-verbose-example-output

Conversation

@ump45nose

Copy link
Copy Markdown
Contributor

Description

The -v/--verbose example in docs/usage_and_configuration/the_basics.md shows two lines that don't match what the CLI actually prints:

  1. Using configuration from /tmp/pyproject.toml. — when the config file is auto-discovered (no --config passed, which is the case in the shown command black src/ -v), main prints Using configuration from project root. (src/black/__init__.py:660-664, the ParameterSource.DEFAULT branch). The message that names the file is spelled Using configuration in '<path>'. and only appears when --config is passed explicitly. So the shown line can never be printed by the shown command.
  2. The summary line ends without a period. get_summary_message always appends a final "." (src/black/report.py:122), and the other summary examples in the same file already end with a period (e.g. line 472).

Two one-token fixes inside the existing fenced block; no prose changes.

Checklist - did you ...

  • Implement any code style changes under the --preview style, following the stability policy? — not applicable (docs only, ticked to show the checklist was read)
  • Add an entry in CHANGES.md if necessary? — not necessary (docs-only; happy to have the skip-changelog label applied)
  • Add / update tests if necessary? — not necessary (no behavior change; no test toolchain available in this environment, and the fix is verified by reading the message-producing code at the base commit)
  • Add new / update outdated documentation? — this PR is the documentation fix

Verification: docs-only; each claim checked against src/black/__init__.py and src/black/report.py at base commit 11cff13. My open PRs #5555 and #5556 edit other line ranges of this same file (quickstart --version example and the INTERNAL ERROR example); the hunks here are disjoint from both.

The auto-discovered config message is 'Using configuration from project root.' (src/black/__init__.py prints it when the config parameter comes from the default source), not 'Using configuration from /tmp/pyproject.toml.'. And the summary line always ends with a period (report.py joins with '.'), as the other examples in the file already show.
@JelleZijlstra JelleZijlstra added the ci: skip news Pull requests that don't need a changelog entry. label Oct 18, 2026
@JelleZijlstra
JelleZijlstra merged commit 50e978a into psf:main Oct 18, 2026
13 of 14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci: skip news Pull requests that don't need a changelog entry.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants