diff --git a/README.md b/README.md index 69ffe6dde20a7d..4bc92a74458633 100644 --- a/README.md +++ b/README.md @@ -352,80 +352,71 @@ Arguments: [FILES]... Options: - --config - Path to the `pyproject.toml` or `ruff.toml` file to use for configuration - -v, --verbose - Enable verbose logging - -q, --quiet - Print lint violations, but nothing else - -s, --silent - Disable all logging (but still exit with status code "1" upon detecting lint violations) - -e, --exit-zero - Exit with status code "0", even upon detecting lint violations - -w, --watch - Run in watch mode by re-running whenever files change - --fix - Attempt to automatically fix lint violations - --fix-only - Fix any fixable lint violations, but don't report on leftover violations. Implies `--fix` - --diff - Avoid writing any fixed files back; instead, output a diff for each changed file to stdout - -n, --no-cache - Disable cache reads - --isolated - Ignore all configuration files + --fix Attempt to automatically fix lint violations + --show-source Show violations with source code + --diff Avoid writing any fixed files back; instead, output a diff for each changed file to stdout + -w, --watch Run in watch mode by re-running whenever files change + --fix-only Fix any fixable lint violations, but don't report on leftover violations. Implies `--fix` + --format Output serialization format for violations [env: RUFF_FORMAT=] [possible values: text, json, junit, grouped, github, gitlab, pylint] + --config Path to the `pyproject.toml` or `ruff.toml` file to use for configuration + --add-noqa Enable automatic additions of `noqa` directives to failing lines + --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 + -V, --version Print version + +Rule selection: --select Comma-separated list of rule codes to enable (or ALL, to enable all rules) - --extend-select - Like --select, but adds additional rule codes on top of the selected ones --ignore Comma-separated list of rule codes to disable + --extend-select + Like --select, but adds additional rule codes on top of the selected ones --extend-ignore Like --ignore, but adds additional rule codes on top of the ignored ones - --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 + --per-file-ignores + List of mappings from file pattern to code to exclude --fixable List of rule codes to treat as eligible for autofix. Only applicable when autofix itself is enabled (e.g., via `--fix`) --unfixable List of rule codes to treat as ineligible for autofix. Only applicable when autofix itself is enabled (e.g., via `--fix`) - --per-file-ignores - List of mappings from file pattern to code to exclude - --format - Output serialization format for violations [env: RUFF_FORMAT=] [possible values: text, json, junit, grouped, github, gitlab, pylint] - --stdin-filename - The name of the file when passing it through stdin - --cache-dir - Path to the cache directory [env: RUFF_CACHE_DIR=] - --show-source - Show violations with source code - --respect-gitignore - Respect file exclusions via `.gitignore` and other standard ignore files - --force-exclude - Enforce exclusions, even for paths passed to Ruff directly on the command-line - --update-check - Enable or disable automatic update checks - --dummy-variable-rgx - Regular expression matching the name of dummy variables + +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 + --force-exclude Enforce exclusions, even for paths passed to Ruff directly on the command-line + +Rule configuration: --target-version The minimum Python version that should be supported --line-length Set the line-length for length-associated rules and automatic formatting - --add-noqa - Enable automatic additions of `noqa` directives to failing lines - --clean - Clear any caches in the current directory or any subdirectories - --explain - Explain a rule - --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 - -V, --version - Print version + --dummy-variable-rgx + Regular expression matching the name of dummy variables + +Miscellaneous: + -n, --no-cache + Disable cache reads + --isolated + Ignore all configuration files + --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 + --update-check + Enable or disable automatic update checks + +Subcommands: + --explain Explain a rule + --clean Clear any caches in the current directory or any subdirectories + +Log levels: + -v, --verbose Enable verbose logging + -q, --quiet Print lint violations, but nothing else + -s, --silent Disable all logging (but still exit with status code "1" upon detecting lint violations) ``` diff --git a/ruff_cli/src/args.rs b/ruff_cli/src/args.rs index 5fe8b9b44544e5..49dc8cb2631cdb 100644 --- a/ruff_cli/src/args.rs +++ b/ruff_cli/src/args.rs @@ -22,113 +22,163 @@ use rustc_hash::FxHashMap; pub struct Args { #[arg(required_unless_present_any = ["clean", "explain", "generate_shell_completion"])] pub files: Vec, - /// Path to the `pyproject.toml` or `ruff.toml` file to use for - /// configuration. - #[arg(long, conflicts_with = "isolated")] - pub config: Option, - #[clap(flatten)] - pub log_level_args: LogLevelArgs, - /// Exit with status code "0", even upon detecting lint violations. - #[arg(short, long)] - pub exit_zero: bool, - /// Run in watch mode by re-running whenever files change. - #[arg(short, long)] - pub watch: bool, /// Attempt to automatically fix lint violations. #[arg(long, overrides_with("no_fix"))] fix: bool, + /// Show violations with source code. + #[arg(long, overrides_with("no_show_source"))] + show_source: bool, + /// Avoid writing any fixed files back; instead, output a diff for each + /// changed file to stdout. + #[arg(long)] + pub diff: bool, #[clap(long, overrides_with("fix"), hide = true)] no_fix: bool, + /// Run in watch mode by re-running whenever files change. + #[arg(short, long)] + pub watch: bool, /// Fix any fixable lint violations, but don't report on leftover /// violations. Implies `--fix`. #[arg(long, overrides_with("no_fix_only"))] fix_only: bool, #[clap(long, overrides_with("fix_only"), hide = true)] no_fix_only: bool, - /// Avoid writing any fixed files back; instead, output a diff for each - /// changed file to stdout. - #[arg(long)] - pub diff: bool, - /// Disable cache reads. - #[arg(short, long)] - pub no_cache: bool, - /// Ignore all configuration files. - #[arg(long, conflicts_with = "config")] - pub isolated: bool, + #[clap(long, overrides_with("show_source"), hide = true)] + no_show_source: bool, + /// Output serialization format for violations. + #[arg(long, value_enum, env = "RUFF_FORMAT")] + pub format: Option, + /// Path to the `pyproject.toml` or `ruff.toml` file to use for + /// configuration. + #[arg(long, conflicts_with = "isolated")] + pub config: Option, /// Comma-separated list of rule codes to enable (or ALL, to enable all /// rules). - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] pub select: Option>, + /// Comma-separated list of rule codes to disable. + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] + pub ignore: Option>, /// Like --select, but adds additional rule codes on top of the selected /// ones. - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] pub extend_select: Option>, - /// Comma-separated list of rule codes to disable. - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] - pub ignore: Option>, /// Like --ignore, but adds additional rule codes on top of the ignored /// ones. - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] pub extend_ignore: Option>, + /// List of mappings from file pattern to code to exclude + #[arg(long, value_delimiter = ',', help_heading = "Rule selection")] + pub per_file_ignores: Option>, /// List of paths, used to omit files and/or directories from analysis. - #[arg(long, value_delimiter = ',', value_name = "FILE_PATTERN")] + #[arg( + long, + value_delimiter = ',', + value_name = "FILE_PATTERN", + help_heading = "File selection" + )] pub exclude: Option>, /// Like --exclude, but adds additional files and directories on top of /// those already excluded. - #[arg(long, value_delimiter = ',', value_name = "FILE_PATTERN")] + #[arg( + long, + value_delimiter = ',', + value_name = "FILE_PATTERN", + help_heading = "File selection" + )] pub extend_exclude: Option>, /// List of rule codes to treat as eligible for autofix. Only applicable /// when autofix itself is enabled (e.g., via `--fix`). - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] pub fixable: Option>, /// List of rule codes to treat as ineligible for autofix. Only applicable /// when autofix itself is enabled (e.g., via `--fix`). - #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")] + #[arg( + long, + value_delimiter = ',', + value_name = "RULE_CODE", + help_heading = "Rule selection" + )] pub unfixable: Option>, - /// List of mappings from file pattern to code to exclude - #[arg(long, value_delimiter = ',')] - pub per_file_ignores: Option>, - /// Output serialization format for violations. - #[arg(long, value_enum, env = "RUFF_FORMAT")] - pub format: Option, - /// The name of the file when passing it through stdin. - #[arg(long)] - pub stdin_filename: Option, - /// Path to the cache directory. - #[arg(long, env = "RUFF_CACHE_DIR")] - pub cache_dir: Option, - /// Show violations with source code. - #[arg(long, overrides_with("no_show_source"))] - show_source: bool, - #[clap(long, overrides_with("show_source"), hide = true)] - no_show_source: bool, /// Respect file exclusions via `.gitignore` and other standard ignore /// files. - #[arg(long, overrides_with("no_respect_gitignore"))] + #[arg( + long, + overrides_with("no_respect_gitignore"), + help_heading = "File selection" + )] respect_gitignore: bool, #[clap(long, overrides_with("respect_gitignore"), hide = true)] no_respect_gitignore: bool, /// Enforce exclusions, even for paths passed to Ruff directly on the /// command-line. - #[arg(long, overrides_with("no_force_exclude"))] + #[arg( + long, + overrides_with("no_force_exclude"), + help_heading = "File selection" + )] force_exclude: bool, #[clap(long, overrides_with("force_exclude"), hide = true)] no_force_exclude: bool, - /// Enable or disable automatic update checks. - #[arg(long, overrides_with("no_update_check"))] - update_check: bool, - #[clap(long, overrides_with("update_check"), hide = true)] - no_update_check: bool, - /// Regular expression matching the name of dummy variables. - #[arg(long)] - pub dummy_variable_rgx: Option, /// The minimum Python version that should be supported. - #[arg(long)] + #[arg(long, help_heading = "Rule configuration")] pub target_version: Option, /// Set the line-length for length-associated rules and automatic /// formatting. - #[arg(long)] + #[arg(long, help_heading = "Rule configuration")] pub line_length: Option, + /// Regular expression matching the name of dummy variables. + #[arg(long, help_heading = "Rule configuration")] + pub dummy_variable_rgx: Option, + /// Disable cache reads. + #[arg(short, long, help_heading = "Miscellaneous")] + pub no_cache: bool, + /// Ignore all configuration files. + #[arg(long, conflicts_with = "config", help_heading = "Miscellaneous")] + pub isolated: bool, + /// Path to the cache directory. + #[arg(long, env = "RUFF_CACHE_DIR", help_heading = "Miscellaneous")] + pub cache_dir: Option, + /// The name of the file when passing it through stdin. + #[arg(long, help_heading = "Miscellaneous")] + pub stdin_filename: Option, + /// Exit with status code "0", even upon detecting lint violations. + #[arg(short, long, help_heading = "Miscellaneous")] + pub exit_zero: bool, + /// Enable or disable automatic update checks. + #[arg( + long, + overrides_with("no_update_check"), + help_heading = "Miscellaneous" + )] + update_check: bool, + #[clap(long, overrides_with("update_check"), hide = true)] + no_update_check: bool, /// Enable automatic additions of `noqa` directives to failing lines. #[arg( long, @@ -143,13 +193,15 @@ pub struct Args { conflicts_with = "watch", )] pub add_noqa: bool, - /// Clear any caches in the current directory or any subdirectories. + /// Explain a rule. #[arg( long, + value_parser=Rule::from_code, + help_heading="Subcommands", // Fake subcommands. conflicts_with = "add_noqa", - // conflicts_with = "clean", - conflicts_with = "explain", + conflicts_with = "clean", + // conflicts_with = "explain", conflicts_with = "generate_shell_completion", conflicts_with = "show_files", conflicts_with = "show_settings", @@ -157,15 +209,15 @@ pub struct Args { conflicts_with = "stdin_filename", conflicts_with = "watch", )] - pub clean: bool, - /// Explain a rule. + pub explain: Option<&'static Rule>, + /// Clear any caches in the current directory or any subdirectories. #[arg( long, - value_parser=Rule::from_code, + help_heading="Subcommands", // Fake subcommands. conflicts_with = "add_noqa", - conflicts_with = "clean", - // conflicts_with = "explain", + // conflicts_with = "clean", + conflicts_with = "explain", conflicts_with = "generate_shell_completion", conflicts_with = "show_files", conflicts_with = "show_settings", @@ -173,7 +225,7 @@ pub struct Args { conflicts_with = "stdin_filename", conflicts_with = "watch", )] - pub explain: Option<&'static Rule>, + pub clean: bool, /// Generate shell completion #[arg( long, @@ -221,20 +273,22 @@ pub struct Args { conflicts_with = "watch", )] pub show_settings: bool, + #[clap(flatten)] + pub log_level_args: LogLevelArgs, } #[allow(clippy::module_name_repetitions)] #[derive(Debug, clap::Args)] pub struct LogLevelArgs { /// Enable verbose logging. - #[arg(short, long, group = "verbosity")] + #[arg(short, long, group = "verbosity", help_heading = "Log levels")] pub verbose: bool, /// Print lint violations, but nothing else. - #[arg(short, long, group = "verbosity")] + #[arg(short, long, group = "verbosity", help_heading = "Log levels")] pub quiet: bool, /// Disable all logging (but still exit with status code "1" upon detecting /// lint violations). - #[arg(short, long, group = "verbosity")] + #[arg(short, long, group = "verbosity", help_heading = "Log levels")] pub silent: bool, }