diff --git a/CHANGES.rst b/CHANGES.rst index 1a8ef8288..7031e7054 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -44,6 +44,7 @@ Added - Document how to set up a development environment, run tests, run linters and update contributors list in ``CONTRIBUTING.rst``. - Document how to pin reformatter/linter versions in ``pre-commit``. +- Clarify configuration of reformatter/linter tools in README and ``--help``. Fixed ----- diff --git a/README.rst b/README.rst index 5ab99cec1..3c2ace819 100644 --- a/README.rst +++ b/README.rst @@ -280,12 +280,25 @@ instead of the last commit: $ darker --revision master . -Customizing ``darker``, Black and isort behavior -================================================ +Customizing ``darker``, Black_, isort_, flynt_ and linter behavior +================================================================== -Project-specific default options for ``darker``, Black_ and isort_ -are read from the project's ``pyproject.toml`` file in the repository root. -isort_ also looks for a few other places for configuration. +``darker`` invokes Black_ and isort_ internals directly instead of running their +binaries, so it needs to read and pass configuration options to them explicitly. +Project-specific default options for ``darker`` itself, Black_ and isort_ are read from +the project's ``pyproject.toml`` file in the repository root. isort_ does also look for +a few other places for configuration. + +Mypy_, Pylint_, Flake8_ and other compatible linters are invoked as +subprocesses by ``darker``, so normal configuration mechanisms apply for each of those +tools. Linters can also be configured on the command line, for example:: + + darker -L "mypy --strict" . + darker --lint "pylint --errors-only" . + +flynt_ (option ``-f`` / ``--flynt``) is also invoked as a subprocess, but passing +command line options to it is currently not supported. Configuration files need to be +used instead. Darker does honor exclusion options in Black configuration files when recursing directories, but the exclusions are only applied to Black reformatting. Isort and @@ -297,6 +310,7 @@ For more details, see: - `Black documentation about pyproject.toml`_ - `isort documentation about config files`_ - `public GitHub repositories which install and run Darker`_ +- `flynt documentation about configuration files`_ The following `command line arguments`_ can also be used to modify the defaults: @@ -324,12 +338,14 @@ The following `command line arguments`_ can also be used to modify the defaults: -i, --isort Also sort imports using the ``isort`` package -L CMD, --lint CMD - Also run a linter on changed files. ``CMD`` can be a name of path of the linter - binary, or a full quoted command line. Highlight linter output syntax if on a - terminal and the ``pygments`` package is available, or if enabled by - configuration. + Also run a linter on changed files. ``CMD`` can be a name or path of the linter + binary, or a full quoted command line with the command and options. Linters read + their configuration as normally, and aren't affected by ``-c`` / ``--config``. + Linter output is syntax highlighted when the ``pygments`` package is available if + run on a terminal and or enabled by explicitly (see ``--color``). -c PATH, --config PATH - Ask ``black`` and ``isort`` to read configuration from ``PATH``. + Ask ``black`` and ``isort`` to read configuration from ``PATH``. Note that other + tools like flynt, Mypy, Pylint and Flake8 won't use this configuration file. -v, --verbose Show steps taken and summarize modifications -q, --quiet @@ -434,6 +450,7 @@ command line options .. _Black documentation about pyproject.toml: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file .. _isort documentation about config files: https://timothycrosley.github.io/isort/docs/configuration/config_files/ .. _public GitHub repositories which install and run Darker: https://github.com/search?q=%2Fpip+install+.*darker%2F+path%3A%2F%5E.github%5C%2Fworkflows%5C%2F.*%2F&type=code +.. _flynt documentation about configuration files: https://github.com/ikamensh/flynt#configuration-files .. _command line arguments: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#command-line-options Editor integration diff --git a/src/darker/help.py b/src/darker/help.py index 6452d59c6..62de3a50a 100644 --- a/src/darker/help.py +++ b/src/darker/help.py @@ -94,13 +94,17 @@ def get_extra_instruction(dependency: str) -> str: ISORT = "".join(ISORT_PARTS) LINT = ( - "Also run a linter on changed files. `CMD` can be a name of path of the" - " linter binary, or a full quoted command line. Highlight linter output syntax if" - " on a terminal and the `pygments` package is available, or if enabled by" - " configuration." + "Also run a linter on changed files. `CMD` can be a name or path of the linter" + " binary, or a full quoted command line with the command and options. Linters read" + " their configuration as normally, and aren't affected by `-c` / `--config`. Linter" + " output is syntax highlighted when the `pygments` package is available if run on" + " a terminal and or enabled by explicitly (see `--color`)." ) -CONFIG = "Ask `black` and `isort` to read configuration from `PATH`." +CONFIG = ( + "Ask `black` and `isort` to read configuration from `PATH`. Note that other tools" + " like flynt, Mypy, Pylint and Flake8 won't use this configuration file." +) VERBOSE = "Show steps taken and summarize modifications" QUIET = "Reduce amount of output"