Add error message instead of simply removing the command/options

Author: MichaReiser

crates/ruff/src/args.rs

@@ -95,6 +95,7 @@ pub enum Command {
     /// Run Ruff on the given files or directories (default).
     Check(CheckCommand),
     /// Explain a rule (or all rules).
+    #[clap(alias = "--explain")]
     #[command(group = clap::ArgGroup::new("selector").multiple(false).required(true))]
     Rule {
         /// Rule to explain
@@ -124,8 +125,10 @@ pub enum Command {
         output_format: HelpFormat,
     },
     /// Clear any caches in the current directory and any subdirectories.
+    #[clap(alias = "--clean")]
     Clean,
     /// Generate shell completion.
+    #[clap(alias = "--generate-shell-completion", hide = true)]
     GenerateShellCompletion { shell: clap_complete_command::Shell },
     /// Run the Ruff formatter on the given files or directories.
     Format(FormatCommand),

crates/ruff/src/lib.rs

@@ -8,12 +8,12 @@ use std::process::ExitCode;
 use std::sync::mpsc::channel;
 
 use anyhow::Result;
-use args::{GlobalConfigArgs, ServerCommand};
 use clap::CommandFactory;
 use colored::Colorize;
 use log::warn;
 use notify::{recommended_watcher, RecursiveMode, Watcher};
 
+use args::{GlobalConfigArgs, ServerCommand};
 use ruff_linter::logging::{set_up_logging, LogLevel};
 use ruff_linter::settings::flags::FixMode;
 use ruff_linter::settings::types::SerializationFormat;
@@ -144,17 +144,6 @@ pub fn run(
         }));
     }
 
-    // Enabled ANSI colors on Windows 10.
-    #[cfg(windows)]
-    assert!(colored::control::set_virtual_terminal(true).is_ok());
-
-    // support FORCE_COLOR env var
-    if let Some(force_color) = std::env::var_os("FORCE_COLOR") {
-        if force_color.len() > 0 {
-            colored::control::set_override(true);
-        }
-    }
-
     set_up_logging(global_options.log_level())?;
 
     match command {

crates/ruff/src/main.rs

@@ -1,10 +1,12 @@
 use std::process::ExitCode;
 
-use clap::Parser;
+use clap::{Parser, Subcommand};
 use colored::Colorize;
+use log::error;
 
-use ruff::args::Args;
+use ruff::args::{Args, Command};
 use ruff::{run, ExitStatus};
+use ruff_linter::logging::{set_up_logging, LogLevel};
 
 #[cfg(target_os = "windows")]
 #[global_allocator]
@@ -23,8 +25,61 @@ static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
 static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
 
 pub fn main() -> ExitCode {
+    // Enabled ANSI colors on Windows 10.
+    #[cfg(windows)]
+    assert!(colored::control::set_virtual_terminal(true).is_ok());
+
+    // support FORCE_COLOR env var
+    if let Some(force_color) = std::env::var_os("FORCE_COLOR") {
+        if force_color.len() > 0 {
+            colored::control::set_override(true);
+        }
+    }
+
     let args = wild::args_os();
     let args = argfile::expand_args_from(args, argfile::parse_fromfile, argfile::PREFIX).unwrap();
+
+    // We can't use `warn_user` here because logging isn't set up at this point
+    // and we also don't know if the user runs ruff with quiet.
+    // Keep the message and pass it to `run` that is responsible for emitting the warning.
+    let deprecated_alias_error = match args.get(1).and_then(|arg| arg.to_str()) {
+        // Deprecated aliases that are handled by clap
+        Some("--explain") => {
+            Some("`ruff --explain <RULE>` has been removed. Use `ruff rule <RULE>` instead.")
+        }
+        Some("--clean") => {
+            Some("`ruff --clean` has been removed. Use `ruff clean` instead.")
+        }
+        Some("--generate-shell-completion") => {
+            Some("`ruff --generate-shell-completion <SHELL>` has been removed. Use `ruff generate-shell-completion <SHELL>` instead.")
+        }
+        // Deprecated `ruff` alias to `ruff check`
+        // Clap doesn't support default subcommands but we want to run `check` by
+        // default for convenience and backwards-compatibility, so we just
+        // preprocess the arguments accordingly before passing them to Clap.
+        Some(arg) if !Command::has_subcommand(arg)
+            && arg != "-h"
+            && arg != "--help"
+            && arg != "-V"
+            && arg != "--version"
+            && arg != "help" => {
+            {
+                Some("`ruff <path>` has been removed. Use `ruff check <path>` instead.")
+            }
+        },
+        _ => None
+    };
+
+    if let Some(error) = deprecated_alias_error {
+        #[allow(clippy::print_stderr)]
+        if set_up_logging(LogLevel::Default).is_ok() {
+            error!("{}", error);
+        } else {
+            eprintln!("{}", error.red().bold());
+        }
+        return ExitCode::FAILURE;
+    }
+
     let args = Args::parse_from(args);
 
     match run(args) {

crates/ruff/tests/integration_test.rs

@@ -1378,6 +1378,7 @@ fn unreadable_pyproject_toml() -> Result<()> {
     // Don't `--isolated` since the configuration discovery is where the error happens
     let args = Args::parse_from(["", "check", "--no-cache", tempdir.path().to_str().unwrap()]);
     let err = run(args).err().context("Unexpected success")?;
+
     assert_eq!(
         err.chain()
             .map(std::string::ToString::to_string)

docs/configuration.md

@@ -521,21 +521,15 @@ Ruff: An extremely fast Python linter.
 Usage: ruff [OPTIONS] <COMMAND>
 
 Commands:
-  check                      Run Ruff on the given files or directories
-                                 (default)
-  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
-  generate-shell-completion  Generate shell completion
-  format                     Run the Ruff formatter on the given files or
-                                 directories
-  server                     Run the language server
-  version                    Display Ruff's version
-  help                       Print this message or the help of the given
-                                 subcommand(s)
+  check    Run Ruff on the given files or directories (default)
+  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
+  version  Display Ruff's version
+  help     Print this message or the help of the given subcommand(s)
 
 Options:
   -h, --help     Print help