From aa5e4c64b14867173f6379334a084ca7b85282c0 Mon Sep 17 00:00:00 2001 From: Mahadev Annabhimoju <219508079+Joosboy@users.noreply.github.com> Date: Tue, 21 Jul 2026 00:09:49 +0530 Subject: [PATCH 1/2] docs: Move CLI docs to top-level command-line interface section --- crates/ruff_dev/src/generate_cli_help.rs | 2 +- docs/cli.md | 406 +++++++++++++++++++++++ docs/configuration.md | 406 ----------------------- mkdocs.template.yml | 1 + scripts/generate_mkdocs.py | 1 + 5 files changed, 409 insertions(+), 407 deletions(-) create mode 100644 docs/cli.md diff --git a/crates/ruff_dev/src/generate_cli_help.rs b/crates/ruff_dev/src/generate_cli_help.rs index 26f2bd52d00965..f64e9dac8964d2 100644 --- a/crates/ruff_dev/src/generate_cli_help.rs +++ b/crates/ruff_dev/src/generate_cli_help.rs @@ -71,7 +71,7 @@ pub(super) fn main(args: &Args) -> Result<()> { } // Read the existing file. - let filename = "docs/configuration.md"; + let filename = "docs/cli.md"; let file = PathBuf::from(ROOT_DIR).join(filename); let existing = fs::read_to_string(&file)?; diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000000000..b027f6ab8303be --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,406 @@ +# Command-line interface + +Some configuration options can be provided or overridden via dedicated flags on the command line. +This includes those related to rule enablement and disablement, +file discovery, logging level, and more: + +```console +$ ruff check path/to/code/ --select F401 --select F403 --quiet +``` + +All other configuration options can be set via the command line +using the `--config` flag, detailed below. + +### The `--config` CLI flag + +The `--config` flag has two uses. It is most often used to point to the +configuration file that you would like Ruff to use, for example: + +```console +$ ruff check path/to/directory --config path/to/ruff.toml +``` + +However, the `--config` flag can also be used to provide arbitrary +overrides of configuration settings using TOML ` = ` pairs. +This is mostly useful in situations where you wish to override a configuration setting +that does not have a dedicated command-line flag. + +In the below example, the `--config` flag is the only way of overriding the +`dummy-variable-rgx` configuration setting from the command line, +since this setting has no dedicated CLI flag. The `per-file-ignores` setting +could also have been overridden via the `--per-file-ignores` dedicated flag, +but using `--config` to override the setting is also fine: + +```console +$ ruff check path/to/file --config path/to/ruff.toml --config "lint.dummy-variable-rgx = '__.*'" --config "lint.per-file-ignores = {'some_file.py' = ['F841']}" +``` + +Configuration options passed to `--config` are parsed in the same way +as configuration options in a `ruff.toml` file. +As such, options specific to the Ruff linter need to be prefixed with `lint.` +(`--config "lint.dummy-variable-rgx = '__.*'"` rather than simply +`--config "dummy-variable-rgx = '__.*'"`), and options specific to the Ruff formatter +need to be prefixed with `format.`. + +If a specific configuration option is simultaneously overridden by +a dedicated flag and by the `--config` flag, the dedicated flag +takes priority. In this example, the maximum permitted line length +will be set to 90, not 100: + +```console +$ ruff format path/to/file --line-length=90 --config "line-length=100" +``` + +Specifying `--config "line-length=90"` will override the `line-length` +setting from *all* configuration files detected by Ruff, +including configuration files discovered in subdirectories. +In this respect, specifying `--config "line-length=90"` has +the same effect as specifying `--line-length=90`, +which will similarly override the `line-length` setting from +all configuration files detected by Ruff, regardless of where +a specific configuration file is located. + +### Full command-line interface + +See `ruff help` for the full list of Ruff's top-level commands: + + + +```text +Ruff: An extremely fast Python linter and code formatter. + +Usage: ruff [OPTIONS] + +Commands: + check Run Ruff on the given files or directories + rule Explain a rule (or all rules) + config List or describe the available configuration options + linter List all supported upstream linters + clean Clear any caches in the current directory and any subdirectories + format Run the Ruff formatter on the given files or directories + server Run the language server + analyze Run analysis over Python source code + version Display Ruff's version + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help (see more with '--help') + -V, --version Print version + +Log levels: + -v, --verbose Enable verbose logging + -q, --quiet Print diagnostics, but nothing else + -s, --silent Disable all logging (but still exit with status code "1" upon + detecting diagnostics) + +Global options: + --config + Either a path to a TOML configuration file (`pyproject.toml` or + `ruff.toml`), or a TOML ` = ` pair (such as you might + find in a `ruff.toml` configuration file) overriding a specific + configuration option (e.g., `--config "lint.line-length = 100"` or + `--config "format.quote-style = 'single'"`). Overrides of individual + settings using this option always take precedence over all + configuration files, including configuration files that were also + specified using `--config` + --isolated + Ignore all configuration files + --color + Control when colored output is used [possible values: auto, always, + never] + +For help with a specific command, see: `ruff help `. +``` + + + +Or `ruff help check` for more on the linting command: + + + +```text +Run Ruff on the given files or directories + +Usage: ruff check [OPTIONS] [FILES]... + +Arguments: + [FILES]... List of files or directories to check, or `-` to read from stdin + [default: .] + +Options: + --fix + Apply fixes to resolve lint violations. Use `--no-fix` to disable or + `--unsafe-fixes` to include unsafe fixes + --unsafe-fixes + Include fixes that may not retain the original intent of the code. + Use `--no-unsafe-fixes` to disable + --show-fixes + Show an enumeration of all fixed lint violations. Use + `--no-show-fixes` to disable + --diff + Avoid writing any fixed files back; instead, output a diff for each + changed file to stdout, and exit 0 if there are no diffs. Implies + `--fix-only` + -w, --watch + Run in watch mode by re-running whenever files change + --fix-only + Apply fixes to resolve lint violations, but don't report on, or exit + non-zero for, leftover violations. Implies `--fix`. Use + `--no-fix-only` to disable or `--unsafe-fixes` to include unsafe + fixes + --ignore-noqa + Ignore any `# noqa` comments + --output-format + Output serialization format for violations. The default serialization + format is "full" [env: RUFF_OUTPUT_FORMAT=] [possible values: + concise, full, json, json-lines, junit, grouped, github, gitlab, + pylint, rdjson, azure, sarif] + -o, --output-file + Specify file to write the linter output to (default: stdout) [env: + RUFF_OUTPUT_FILE=] + --target-version + The minimum Python version that should be supported [possible values: + py37, py38, py39, py310, py311, py312, py313, py314, py315] + --preview + Enable preview mode; checks will include unstable rules and fixes. + Use `--no-preview` to disable + --extension + List of mappings from file extension to language (one of `python`, + `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython + notebooks, use `--extension ipy:ipynb` + --statistics + Show counts for every rule with at least one violation + --add-noqa[=] + Enable automatic additions of `noqa` directives to failing lines. + Optionally provide a reason to append after the codes + --add-ignore[=] + Enable automatic additions of `ruff:ignore` comments to failing + lines. Optionally provide a reason to append after the rule names. + Requires preview mode + --show-files + See the files Ruff will be run against with the current settings + --show-settings + See the settings Ruff will use to lint a given Python file + -h, --help + Print help (see more with '--help') + +Rule selection: + --select + Comma-separated list of rule codes to enable (or ALL, to enable all + rules) + --ignore + Comma-separated list of rule codes to disable + --extend-select + Like --select, but adds additional rule codes on top of those already + specified + --per-file-ignores + List of mappings from file pattern to code to exclude + --extend-per-file-ignores + Like `--per-file-ignores`, but adds additional ignores on top of + those already specified + --fixable + List of rule codes to treat as eligible for fix. Only applicable when + fix itself is enabled (e.g., via `--fix`) + --unfixable + List of rule codes to treat as ineligible for fix. Only applicable + when fix itself is enabled (e.g., via `--fix`) + --extend-fixable + Like --fixable, but adds additional rule codes on top of those + already specified + +File selection: + --exclude + List of paths, used to omit files and/or directories from analysis + --extend-exclude + Like --exclude, but adds additional files and directories on top of + those already excluded + --respect-gitignore + Respect file exclusions via `.gitignore` and other standard ignore + files. Use `--no-respect-gitignore` to disable + --force-exclude + Enforce exclusions, even for paths passed to Ruff directly on the + command-line. Use `--no-force-exclude` to disable + +Miscellaneous: + -n, --no-cache + Disable cache reads [env: RUFF_NO_CACHE=] + --cache-dir + Path to the cache directory [env: RUFF_CACHE_DIR=] + --stdin-filename + The name of the file when passing it through stdin + -e, --exit-zero + Exit with status code "0", even upon detecting lint violations + --exit-non-zero-on-fix + Exit with a non-zero status code if any files were modified via fix, + even if no lint violations remain + +Log levels: + -v, --verbose Enable verbose logging + -q, --quiet Print diagnostics, but nothing else + -s, --silent Disable all logging (but still exit with status code "1" upon + detecting diagnostics) + +Global options: + --config + Either a path to a TOML configuration file (`pyproject.toml` or + `ruff.toml`), or a TOML ` = ` pair (such as you might + find in a `ruff.toml` configuration file) overriding a specific + configuration option (e.g., `--config "lint.line-length = 100"` or + `--config "format.quote-style = 'single'"`). Overrides of individual + settings using this option always take precedence over all + configuration files, including configuration files that were also + specified using `--config` + --isolated + Ignore all configuration files + --color + Control when colored output is used [possible values: auto, always, + never] +``` + + + +Or `ruff help format` for more on the formatting command: + + + +```text +Run the Ruff formatter on the given files or directories + +Usage: ruff format [OPTIONS] [FILES]... + +Arguments: + [FILES]... List of files or directories to format, or `-` to read from stdin + [default: .] + +Options: + --check + Avoid writing any formatted files back; instead, exit with a non-zero + status code if any files would have been modified, and zero otherwise + --diff + Avoid writing any formatted files back; instead, exit with a non-zero + status code and the difference between the current file and how the + formatted file would look like + --extension + List of mappings from file extension to language (one of `python`, + `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython + notebooks, use `--extension ipy:ipynb` + --target-version + The minimum Python version that should be supported [possible values: + py37, py38, py39, py310, py311, py312, py313, py314, py315] + --preview + Enable preview mode; enables unstable formatting. Use `--no-preview` + to disable + --output-format + Output serialization format for violations, when used with `--check`. + The default serialization format is "full" [env: RUFF_OUTPUT_FORMAT=] + [possible values: concise, full, json, json-lines, junit, grouped, + github, gitlab, pylint, rdjson, azure, sarif] + -h, --help + Print help (see more with '--help') + +Miscellaneous: + -n, --no-cache + Disable cache reads [env: RUFF_NO_CACHE=] + --cache-dir + Path to the cache directory [env: RUFF_CACHE_DIR=] + --stdin-filename + The name of the file when passing it through stdin + --exit-non-zero-on-format + Exit with a non-zero status code if any files were modified via + format, even if all files were formatted successfully + +File selection: + --respect-gitignore + Respect file exclusions via `.gitignore` and other standard ignore + files. Use `--no-respect-gitignore` to disable + --exclude + List of paths, used to omit files and/or directories from analysis + --extend-exclude + Like --exclude, but adds additional files and directories on top of + those already excluded + --force-exclude + Enforce exclusions, even for paths passed to Ruff directly on the + command-line. Use `--no-force-exclude` to disable + +Format configuration: + --line-length Set the line-length + +Editor options: + --range When specified, Ruff will try to only format the code in + the given range. + It might be necessary to extend the start backwards or + the end forwards, to fully enclose a logical line. + The `` uses the format + `:-:`. + +Log levels: + -v, --verbose Enable verbose logging + -q, --quiet Print diagnostics, but nothing else + -s, --silent Disable all logging (but still exit with status code "1" upon + detecting diagnostics) + +Global options: + --config + Either a path to a TOML configuration file (`pyproject.toml` or + `ruff.toml`), or a TOML ` = ` pair (such as you might + find in a `ruff.toml` configuration file) overriding a specific + configuration option (e.g., `--config "lint.line-length = 100"` or + `--config "format.quote-style = 'single'"`). Overrides of individual + settings using this option always take precedence over all + configuration files, including configuration files that were also + specified using `--config` + --isolated + Ignore all configuration files + --color + Control when colored output is used [possible values: auto, always, + never] +``` + + + +## Shell autocompletion + +Ruff supports autocompletion for most shells. A shell-specific completion script can be generated +by `ruff generate-shell-completion `, where `` is one of `bash`, `elvish`, `fig`, `fish`, +`powershell`, or `zsh`. + +!!! tip + + You can run `echo $SHELL` to help you determine your shell. + +To enable shell autocompletion for Ruff, run one of the following: + +=== "Bash" + + ```bash + echo 'eval "$(ruff generate-shell-completion bash)"' >> ~/.bashrc + ``` + +=== "Zsh" + + ```bash + echo 'eval "$(ruff generate-shell-completion zsh)"' >> ~/.zshrc + ``` + +=== "fish" + + ```bash + echo 'ruff generate-shell-completion fish | source' > ~/.config/fish/completions/ruff.fish + ``` + +=== "Elvish" + + ```bash + echo 'eval (ruff generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv + ``` + +=== "PowerShell / pwsh" + + ```powershell + if (!(Test-Path -Path $PROFILE)) { + New-Item -ItemType File -Path $PROFILE -Force + } + Add-Content -Path $PROFILE -Value '(& ruff generate-shell-completion powershell) | Out-String | Invoke-Expression' + ``` + +Then restart the shell or source the shell config file. diff --git a/docs/configuration.md b/docs/configuration.md index 3b424f66aac7a6..601740052fc498 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -454,409 +454,3 @@ rule detect imports at the top of a file, but for notebooks it detects imports a **cell**. For a given rule, the rule's documentation will always specify if it has different behavior when applied to Jupyter Notebook files. -## Command-line interface - -Some configuration options can be provided or overridden via dedicated flags on the command line. -This includes those related to rule enablement and disablement, -file discovery, logging level, and more: - -```console -$ ruff check path/to/code/ --select F401 --select F403 --quiet -``` - -All other configuration options can be set via the command line -using the `--config` flag, detailed below. - -### The `--config` CLI flag - -The `--config` flag has two uses. It is most often used to point to the -configuration file that you would like Ruff to use, for example: - -```console -$ ruff check path/to/directory --config path/to/ruff.toml -``` - -However, the `--config` flag can also be used to provide arbitrary -overrides of configuration settings using TOML ` = ` pairs. -This is mostly useful in situations where you wish to override a configuration setting -that does not have a dedicated command-line flag. - -In the below example, the `--config` flag is the only way of overriding the -`dummy-variable-rgx` configuration setting from the command line, -since this setting has no dedicated CLI flag. The `per-file-ignores` setting -could also have been overridden via the `--per-file-ignores` dedicated flag, -but using `--config` to override the setting is also fine: - -```console -$ ruff check path/to/file --config path/to/ruff.toml --config "lint.dummy-variable-rgx = '__.*'" --config "lint.per-file-ignores = {'some_file.py' = ['F841']}" -``` - -Configuration options passed to `--config` are parsed in the same way -as configuration options in a `ruff.toml` file. -As such, options specific to the Ruff linter need to be prefixed with `lint.` -(`--config "lint.dummy-variable-rgx = '__.*'"` rather than simply -`--config "dummy-variable-rgx = '__.*'"`), and options specific to the Ruff formatter -need to be prefixed with `format.`. - -If a specific configuration option is simultaneously overridden by -a dedicated flag and by the `--config` flag, the dedicated flag -takes priority. In this example, the maximum permitted line length -will be set to 90, not 100: - -```console -$ ruff format path/to/file --line-length=90 --config "line-length=100" -``` - -Specifying `--config "line-length=90"` will override the `line-length` -setting from *all* configuration files detected by Ruff, -including configuration files discovered in subdirectories. -In this respect, specifying `--config "line-length=90"` has -the same effect as specifying `--line-length=90`, -which will similarly override the `line-length` setting from -all configuration files detected by Ruff, regardless of where -a specific configuration file is located. - -### Full command-line interface - -See `ruff help` for the full list of Ruff's top-level commands: - - - -```text -Ruff: An extremely fast Python linter and code formatter. - -Usage: ruff [OPTIONS] - -Commands: - check Run Ruff on the given files or directories - rule Explain a rule (or all rules) - config List or describe the available configuration options - linter List all supported upstream linters - clean Clear any caches in the current directory and any subdirectories - format Run the Ruff formatter on the given files or directories - server Run the language server - analyze Run analysis over Python source code - version Display Ruff's version - help Print this message or the help of the given subcommand(s) - -Options: - -h, --help Print help (see more with '--help') - -V, --version Print version - -Log levels: - -v, --verbose Enable verbose logging - -q, --quiet Print diagnostics, but nothing else - -s, --silent Disable all logging (but still exit with status code "1" upon - detecting diagnostics) - -Global options: - --config - Either a path to a TOML configuration file (`pyproject.toml` or - `ruff.toml`), or a TOML ` = ` pair (such as you might - find in a `ruff.toml` configuration file) overriding a specific - configuration option (e.g., `--config "lint.line-length = 100"` or - `--config "format.quote-style = 'single'"`). Overrides of individual - settings using this option always take precedence over all - configuration files, including configuration files that were also - specified using `--config` - --isolated - Ignore all configuration files - --color - Control when colored output is used [possible values: auto, always, - never] - -For help with a specific command, see: `ruff help `. -``` - - - -Or `ruff help check` for more on the linting command: - - - -```text -Run Ruff on the given files or directories - -Usage: ruff check [OPTIONS] [FILES]... - -Arguments: - [FILES]... List of files or directories to check, or `-` to read from stdin - [default: .] - -Options: - --fix - Apply fixes to resolve lint violations. Use `--no-fix` to disable or - `--unsafe-fixes` to include unsafe fixes - --unsafe-fixes - Include fixes that may not retain the original intent of the code. - Use `--no-unsafe-fixes` to disable - --show-fixes - Show an enumeration of all fixed lint violations. Use - `--no-show-fixes` to disable - --diff - Avoid writing any fixed files back; instead, output a diff for each - changed file to stdout, and exit 0 if there are no diffs. Implies - `--fix-only` - -w, --watch - Run in watch mode by re-running whenever files change - --fix-only - Apply fixes to resolve lint violations, but don't report on, or exit - non-zero for, leftover violations. Implies `--fix`. Use - `--no-fix-only` to disable or `--unsafe-fixes` to include unsafe - fixes - --ignore-noqa - Ignore any `# noqa` comments - --output-format - Output serialization format for violations. The default serialization - format is "full" [env: RUFF_OUTPUT_FORMAT=] [possible values: - concise, full, json, json-lines, junit, grouped, github, gitlab, - pylint, rdjson, azure, sarif] - -o, --output-file - Specify file to write the linter output to (default: stdout) [env: - RUFF_OUTPUT_FILE=] - --target-version - The minimum Python version that should be supported [possible values: - py37, py38, py39, py310, py311, py312, py313, py314, py315] - --preview - Enable preview mode; checks will include unstable rules and fixes. - Use `--no-preview` to disable - --extension - List of mappings from file extension to language (one of `python`, - `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython - notebooks, use `--extension ipy:ipynb` - --statistics - Show counts for every rule with at least one violation - --add-noqa[=] - Enable automatic additions of `noqa` directives to failing lines. - Optionally provide a reason to append after the codes - --add-ignore[=] - Enable automatic additions of `ruff:ignore` comments to failing - lines. Optionally provide a reason to append after the rule names. - Requires preview mode - --show-files - See the files Ruff will be run against with the current settings - --show-settings - See the settings Ruff will use to lint a given Python file - -h, --help - Print help (see more with '--help') - -Rule selection: - --select - Comma-separated list of rule codes to enable (or ALL, to enable all - rules) - --ignore - Comma-separated list of rule codes to disable - --extend-select - Like --select, but adds additional rule codes on top of those already - specified - --per-file-ignores - List of mappings from file pattern to code to exclude - --extend-per-file-ignores - Like `--per-file-ignores`, but adds additional ignores on top of - those already specified - --fixable - List of rule codes to treat as eligible for fix. Only applicable when - fix itself is enabled (e.g., via `--fix`) - --unfixable - List of rule codes to treat as ineligible for fix. Only applicable - when fix itself is enabled (e.g., via `--fix`) - --extend-fixable - Like --fixable, but adds additional rule codes on top of those - already specified - -File selection: - --exclude - List of paths, used to omit files and/or directories from analysis - --extend-exclude - Like --exclude, but adds additional files and directories on top of - those already excluded - --respect-gitignore - Respect file exclusions via `.gitignore` and other standard ignore - files. Use `--no-respect-gitignore` to disable - --force-exclude - Enforce exclusions, even for paths passed to Ruff directly on the - command-line. Use `--no-force-exclude` to disable - -Miscellaneous: - -n, --no-cache - Disable cache reads [env: RUFF_NO_CACHE=] - --cache-dir - Path to the cache directory [env: RUFF_CACHE_DIR=] - --stdin-filename - The name of the file when passing it through stdin - -e, --exit-zero - Exit with status code "0", even upon detecting lint violations - --exit-non-zero-on-fix - Exit with a non-zero status code if any files were modified via fix, - even if no lint violations remain - -Log levels: - -v, --verbose Enable verbose logging - -q, --quiet Print diagnostics, but nothing else - -s, --silent Disable all logging (but still exit with status code "1" upon - detecting diagnostics) - -Global options: - --config - Either a path to a TOML configuration file (`pyproject.toml` or - `ruff.toml`), or a TOML ` = ` pair (such as you might - find in a `ruff.toml` configuration file) overriding a specific - configuration option (e.g., `--config "lint.line-length = 100"` or - `--config "format.quote-style = 'single'"`). Overrides of individual - settings using this option always take precedence over all - configuration files, including configuration files that were also - specified using `--config` - --isolated - Ignore all configuration files - --color - Control when colored output is used [possible values: auto, always, - never] -``` - - - -Or `ruff help format` for more on the formatting command: - - - -```text -Run the Ruff formatter on the given files or directories - -Usage: ruff format [OPTIONS] [FILES]... - -Arguments: - [FILES]... List of files or directories to format, or `-` to read from stdin - [default: .] - -Options: - --check - Avoid writing any formatted files back; instead, exit with a non-zero - status code if any files would have been modified, and zero otherwise - --diff - Avoid writing any formatted files back; instead, exit with a non-zero - status code and the difference between the current file and how the - formatted file would look like - --extension - List of mappings from file extension to language (one of `python`, - `ipynb`, `pyi`). For example, to treat `.ipy` files as IPython - notebooks, use `--extension ipy:ipynb` - --target-version - The minimum Python version that should be supported [possible values: - py37, py38, py39, py310, py311, py312, py313, py314, py315] - --preview - Enable preview mode; enables unstable formatting. Use `--no-preview` - to disable - --output-format - Output serialization format for violations, when used with `--check`. - The default serialization format is "full" [env: RUFF_OUTPUT_FORMAT=] - [possible values: concise, full, json, json-lines, junit, grouped, - github, gitlab, pylint, rdjson, azure, sarif] - -h, --help - Print help (see more with '--help') - -Miscellaneous: - -n, --no-cache - Disable cache reads [env: RUFF_NO_CACHE=] - --cache-dir - Path to the cache directory [env: RUFF_CACHE_DIR=] - --stdin-filename - The name of the file when passing it through stdin - --exit-non-zero-on-format - Exit with a non-zero status code if any files were modified via - format, even if all files were formatted successfully - -File selection: - --respect-gitignore - Respect file exclusions via `.gitignore` and other standard ignore - files. Use `--no-respect-gitignore` to disable - --exclude - List of paths, used to omit files and/or directories from analysis - --extend-exclude - Like --exclude, but adds additional files and directories on top of - those already excluded - --force-exclude - Enforce exclusions, even for paths passed to Ruff directly on the - command-line. Use `--no-force-exclude` to disable - -Format configuration: - --line-length Set the line-length - -Editor options: - --range When specified, Ruff will try to only format the code in - the given range. - It might be necessary to extend the start backwards or - the end forwards, to fully enclose a logical line. - The `` uses the format - `:-:`. - -Log levels: - -v, --verbose Enable verbose logging - -q, --quiet Print diagnostics, but nothing else - -s, --silent Disable all logging (but still exit with status code "1" upon - detecting diagnostics) - -Global options: - --config - Either a path to a TOML configuration file (`pyproject.toml` or - `ruff.toml`), or a TOML ` = ` pair (such as you might - find in a `ruff.toml` configuration file) overriding a specific - configuration option (e.g., `--config "lint.line-length = 100"` or - `--config "format.quote-style = 'single'"`). Overrides of individual - settings using this option always take precedence over all - configuration files, including configuration files that were also - specified using `--config` - --isolated - Ignore all configuration files - --color - Control when colored output is used [possible values: auto, always, - never] -``` - - - -## Shell autocompletion - -Ruff supports autocompletion for most shells. A shell-specific completion script can be generated -by `ruff generate-shell-completion `, where `` is one of `bash`, `elvish`, `fig`, `fish`, -`powershell`, or `zsh`. - -!!! tip - - You can run `echo $SHELL` to help you determine your shell. - -To enable shell autocompletion for Ruff, run one of the following: - -=== "Bash" - - ```bash - echo 'eval "$(ruff generate-shell-completion bash)"' >> ~/.bashrc - ``` - -=== "Zsh" - - ```bash - echo 'eval "$(ruff generate-shell-completion zsh)"' >> ~/.zshrc - ``` - -=== "fish" - - ```bash - echo 'ruff generate-shell-completion fish | source' > ~/.config/fish/completions/ruff.fish - ``` - -=== "Elvish" - - ```bash - echo 'eval (ruff generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv - ``` - -=== "PowerShell / pwsh" - - ```powershell - if (!(Test-Path -Path $PROFILE)) { - New-Item -ItemType File -Path $PROFILE -Force - } - Add-Content -Path $PROFILE -Value '(& ruff generate-shell-completion powershell) | Out-String | Invoke-Expression' - ``` - -Then restart the shell or source the shell config file. diff --git a/mkdocs.template.yml b/mkdocs.template.yml index cdbc32c983be91..3a1c0035edcea9 100644 --- a/mkdocs.template.yml +++ b/mkdocs.template.yml @@ -81,6 +81,7 @@ plugins: - tutorial.md Configuration: - configuration.md + - cli.md Linter: - linter.md Formatter: diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index 564d7c1a341aa4..d755df01f283c6 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -45,6 +45,7 @@ class Section(NamedTuple): ], ), Section("Configuring Ruff", "configuration.md", generated=False), + Section("Command-line Interface", "cli.md", generated=False), Section("Preview", "preview.md", generated=False), Section("Rules", "rules.md", generated=True), Section("Settings", "settings.md", generated=True), From 54f1e8993bce66d7183935bfe969da67e0e1768c Mon Sep 17 00:00:00 2001 From: Mahadev Annabhimoju <219508079+Joosboy@users.noreply.github.com> Date: Tue, 21 Jul 2026 00:14:02 +0530 Subject: [PATCH 2/2] Docs: Include in CLI docs to resolve #13444 --- crates/ruff_dev/src/generate_cli_help.rs | 13 ++++++++ docs/cli.md | 41 ++++++++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/crates/ruff_dev/src/generate_cli_help.rs b/crates/ruff_dev/src/generate_cli_help.rs index f64e9dac8964d2..f19833934f0b8e 100644 --- a/crates/ruff_dev/src/generate_cli_help.rs +++ b/crates/ruff_dev/src/generate_cli_help.rs @@ -21,6 +21,9 @@ const CHECK_HELP_END_PRAGMA: &str = ""; const FORMAT_HELP_BEGIN_PRAGMA: &str = "\n"; const FORMAT_HELP_END_PRAGMA: &str = ""; +const ANALYZE_HELP_BEGIN_PRAGMA: &str = "\n"; +const ANALYZE_HELP_END_PRAGMA: &str = ""; + #[derive(clap::Args)] pub(crate) struct Args { #[arg(long, default_value_t, value_enum)] @@ -63,10 +66,14 @@ pub(super) fn main(args: &Args) -> Result<()> { // Generate `ruff help format`. let format_help = trim_lines(&subcommand_help_text("format")?); + // Generate `ruff help analyze`. + let analyze_help = trim_lines(&subcommand_help_text("analyze")?); + if args.mode.is_dry_run() { print!("{command_help}"); print!("{check_help}"); print!("{format_help}"); + print!("{analyze_help}"); return Ok(()); } @@ -93,6 +100,12 @@ pub(super) fn main(args: &Args) -> Result<()> { FORMAT_HELP_BEGIN_PRAGMA, FORMAT_HELP_END_PRAGMA, )?; + let new = replace_docs_section( + &new, + &format!("```text\n{analyze_help}\n```\n\n"), + ANALYZE_HELP_BEGIN_PRAGMA, + ANALYZE_HELP_END_PRAGMA, + )?; match args.mode { Mode::Check => { diff --git a/docs/cli.md b/docs/cli.md index b027f6ab8303be..e2c71ea4fd7a48 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -358,6 +358,47 @@ Global options: +Or `ruff help analyze` for more on the analysis command: + + + +```text +Run analysis over Python source code + +Usage: ruff analyze [OPTIONS] + +Commands: + graph Generate a map of Python file dependencies or dependents + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help Print help (see more with '--help') + +Log levels: + -v, --verbose Enable verbose logging + -q, --quiet Print diagnostics, but nothing else + -s, --silent Disable all logging (but still exit with status code "1" upon + detecting diagnostics) + +Global options: + --config + Either a path to a TOML configuration file (`pyproject.toml` or + `ruff.toml`), or a TOML ` = ` pair (such as you might + find in a `ruff.toml` configuration file) overriding a specific + configuration option (e.g., `--config "lint.line-length = 100"` or + `--config "format.quote-style = 'single'"`). Overrides of individual + settings using this option always take precedence over all + configuration files, including configuration files that were also + specified using `--config` + --isolated + Ignore all configuration files + --color + Control when colored output is used [possible values: auto, always, + never] +``` + + + ## Shell autocompletion Ruff supports autocompletion for most shells. A shell-specific completion script can be generated