-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs (linter.md
): clarify that Python files are always searched for in subdirectories
#15882
Conversation
docs/linter.md
Outdated
`ruff check` is the primary entrypoint to the Ruff linter. It accepts a list of files or | ||
directories, and lints all discovered Python files, optionally fixing any fixable errors: | ||
directories, and lints all discovered Python files (including those in subdirectories), optionally | ||
fixing any fixable errors: | ||
|
||
```console | ||
$ ruff check # Lint all files in the current directory. | ||
$ ruff check --fix # Lint all files in the current directory, and fix any fixable errors. | ||
$ ruff check --watch # Lint all files in the current directory, and re-lint on change. | ||
$ ruff check path/to/code/ # Lint all files in `path/to/code` (and any subdirectories). | ||
$ ruff check # Lint files in the current directory and any subdirectories. | ||
$ ruff check --fix # Lint files in the current directory and any subdirectories and fix any fixable errors. | ||
$ ruff check --watch # Lint files in the current directory and any subdirectories and re-lint on change. | ||
$ ruff check path/to/code/ # Lint files in `path/to/code` and any subdirectories. | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can see how this is unclear on main
, but the suggested rewording here does feel a little repetitive now. What about something like this?
`ruff check` is the primary entrypoint to the Ruff linter. It accepts a list of files or
directories, and lints all discovered Python files, optionally fixing any fixable errors.
When linting a directory, Ruff searches for Python files recursively in that directory
and all its subdirectories:
```console
$ ruff check # Lint all files in the current directory.
$ ruff check --fix # Lint all files in the current directory, and fix any fixable errors.
$ ruff check --watch # Lint all files in the current directory, and re-lint on change.
$ ruff check path/to/code/ # Lint all files in `path/to/code`
```
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mmm, yes that's better! Well done :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PS do you have opinions on:
Lint all files in the current directory.
vs.
Lint files starting from the current directory.
I prefer the latter since it hints there is some filtering and recursion without losing clarity, e.g. only Python files, respect .gitignore, etc.
linter.md
linter.md
): clarify that Python files are always searched for in subdirectories
…n subdirectories.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks!
* main: (66 commits) [red-knot] Use ternary decision diagrams (TDDs) for visibility constraints (#15861) [`pyupgrade`] Rename private type parameters in PEP 695 generics (`UP049`) (#15862) Simplify the `StringFlags` trait (#15944) [`flake8-pyi`] Make `PYI019` autofixable for `.py` files in preview mode as well as stubs (#15889) Docs (`linter.md`): clarify that Python files are always searched for in subdirectories (#15882) [`flake8-pyi`] Make PEP-695 functions with multiple type parameters fixable by PYI019 again (#15938) [red-knot] Use unambiguous invalid-syntax-construct for suppression comment test (#15933) Make `Binding::range()` point to the range of a type parameter's name, not the full type parameter (#15935) Update black deviations (#15928) [red-knot] MDTest: Fix line numbers in error messages (#15932) Preserve triple quotes and prefixes for strings (#15818) [red-knot] Hand-written MDTest parser (#15926) [`pylint`] Fix missing parens in unsafe fix for `unnecessary-dunder-call` (`PLC2801`) (#15762) nit: docs for ignore & select (#15883) [airflow] `BashOperator` has been moved to `airflow.providers.standard.operators.bash.BashOperator` (AIR302) (#15922) [`flake8-logging`] `.exception()` and `exc_info=` outside exception handlers (`LOG004`, `LOG014`) (#15799) [red-knot] Enforce specifying paths for mdtest code blocks in a separate preceding line (#15890) [red-knot] Internal refactoring of visibility constraints API (#15913) [red-knot] Implicit instance attributes (#15811) [`flake8-comprehensions`] Handle extraneous parentheses around list comprehension (`C403`) (#15877) ...
Nits related to clarity of which files are linted
Hi!
I noticed no mention of recursing through sub-dirs and only the fourth example:
ruff check path/to/code/
included the phrase: "and any subdirectories" leading me to believe only providing a path would recurse and the others would not. I don't think that's the actual behavior. It does feel a bit repetitive to say so in each example and in the intro paragraph, but I do somewhat like the clarity.Also, I opted to remove the "all" from "Lint all files in the current directory." (and others) since I presume it doesn't lint all files, only "all discovered Python files". Without the "all", I think it's clear many files will be linted, and it gives
a hint that further logic exists for filtering.