Rename format option to output-format (#7514)

crates/ruff_cli/src/args.rs

@@ -109,9 +109,21 @@ pub struct CheckCommand {
     /// Ignore any `# noqa` comments.
     #[arg(long)]
     ignore_noqa: bool,
-    /// Output serialization format for violations.
+
-    #[arg(long, value_enum, env = "RUFF_FORMAT")]
+    /// Output serialization format for violations. (Deprecated: Use `--output-format` instead).
+    #[arg(
+        long,
+        value_enum,
+        env = "RUFF_FORMAT",
+        conflicts_with = "output_format",
+        hide = true
+    )]
     pub format: Option<SerializationFormat>,
+
+    /// Output serialization format for violations.
+    #[arg(long, value_enum, env = "RUFF_OUTPUT_FORMAT")]
+    pub output_format: Option<SerializationFormat>,
+
     /// Specify file to write the linter output to (default: stdout).
     #[arg(short, long)]
     pub output_file: Option<PathBuf>,
@@ -486,7 +498,7 @@ impl CheckCommand {
                 fix: resolve_bool_arg(self.fix, self.no_fix),
                 fix_only: resolve_bool_arg(self.fix_only, self.no_fix_only),
                 force_exclude: resolve_bool_arg(self.force_exclude, self.no_force_exclude),
-                format: self.format,
+                output_format: self.output_format.or(self.format),
                 show_fixes: resolve_bool_arg(self.show_fixes, self.no_show_fixes),
             },
         )
@@ -588,7 +600,7 @@ pub struct Overrides {
     pub fix: Option<bool>,
     pub fix_only: Option<bool>,
     pub force_exclude: Option<bool>,
-    pub format: Option<SerializationFormat>,
+    pub output_format: Option<SerializationFormat>,
     pub show_fixes: Option<bool>,
 }
 
@@ -632,8 +644,8 @@ impl ConfigProcessor for Overrides {
                 .collect(),
             extend_fixable: self.extend_fixable.clone().unwrap_or_default(),
         });
-        if let Some(format) = &self.format {
+        if let Some(output_format) = &self.output_format {
-            config.format = Some(*format);
+            config.output_format = Some(*output_format);
         }
         if let Some(force_exclude) = &self.force_exclude {
             config.force_exclude = Some(*force_exclude);

crates/ruff_cli/src/lib.rs

@@ -12,7 +12,7 @@ use notify::{recommended_watcher, RecursiveMode, Watcher};
 use ruff_linter::logging::{set_up_logging, LogLevel};
 use ruff_linter::settings::types::SerializationFormat;
 use ruff_linter::settings::{flags, CliSettings};
-use ruff_linter::{fs, warn_user_once};
+use ruff_linter::{fs, warn_user, warn_user_once};
 
 use crate::args::{Args, CheckCommand, Command, FormatCommand};
 use crate::printer::{Flags as PrinterFlags, Printer};
@@ -180,6 +180,14 @@ fn format(args: FormatCommand, log_level: LogLevel) -> Result<ExitStatus> {
 }
 
 pub fn check(args: CheckCommand, log_level: LogLevel) -> Result<ExitStatus> {
+    if args.format.is_some() {
+        if std::env::var("RUFF_FORMAT").is_ok() {
+            warn_user!("The environment variable `RUFF_FORMAT` is deprecated. Use `RUFF_OUTPUT_FORMAT` instead.");
+        } else {
+            warn_user!("The argument `--format=<FORMAT>` is deprecated. Use `--output-format=<FORMAT>` instead.");
+        }
+    }
+
     let (cli, overrides) = args.partition();
 
     // Construct the "default" settings. These are used when no `pyproject.toml`
@@ -219,7 +227,7 @@ pub fn check(args: CheckCommand, log_level: LogLevel) -> Result<ExitStatus> {
     let CliSettings {
         fix,
         fix_only,
-        format,
+        output_format,
         show_fixes,
         show_source,
         ..
@@ -251,7 +259,7 @@ pub fn check(args: CheckCommand, log_level: LogLevel) -> Result<ExitStatus> {
         printer_flags |= PrinterFlags::SHOW_SOURCE;
     }
     if cli.ecosystem_ci {
-        warn_user_once!(
+        warn_user!(
             "The formatting of fixes emitted by this option is a work-in-progress, subject to \
             change at any time, and intended only for internal use."
         );
@@ -262,12 +270,12 @@ pub fn check(args: CheckCommand, log_level: LogLevel) -> Result<ExitStatus> {
     if cache {
         // `--no-cache` doesn't respect code changes, and so is often confusing during
         // development.
-        warn_user_once!("Detected debug build without --no-cache.");
+        warn_user!("Detected debug build without --no-cache.");
     }
 
     if cli.add_noqa {
         if !autofix.is_generate() {
-            warn_user_once!("--fix is incompatible with --add-noqa.");
+            warn_user!("--fix is incompatible with --add-noqa.");
         }
         let modifications =
             commands::add_noqa::add_noqa(&cli.files, &pyproject_config, &overrides)?;
@@ -281,11 +289,11 @@ pub fn check(args: CheckCommand, log_level: LogLevel) -> Result<ExitStatus> {
         return Ok(ExitStatus::Success);
     }
 
-    let printer = Printer::new(format, log_level, autofix, printer_flags);
+    let printer = Printer::new(output_format, log_level, autofix, printer_flags);
 
     if cli.watch {
-        if format != SerializationFormat::Text {
+        if output_format != SerializationFormat::Text {
-            warn_user_once!("--format 'text' is used in watch mode.");
+            warn_user!("--format 'text' is used in watch mode.");
         }
 
         // Configure the file watcher.

crates/ruff_cli/tests/integration_test.rs

@@ -28,7 +28,7 @@ use ruff_cli::args::Args;
 use ruff_cli::run;
 
 const BIN_NAME: &str = "ruff";
-const STDIN_BASE_OPTIONS: &[&str] = &["--isolated", "--no-cache", "-", "--format", "text"];
+const STDIN_BASE_OPTIONS: &[&str] = &["--isolated", "--no-cache", "-", "--output-format", "text"];
 
 #[test]
 fn stdin_success() {
@@ -117,7 +117,7 @@ fn stdin_json() {
         "-",
         "--isolated",
         "--no-cache",
-        "--format",
+        "--output-format",
         "json",
         "--stdin-filename",
         "F401.py",
@@ -551,6 +551,7 @@ fn check_input_from_argfile() -> Result<()> {
     let args = vec![
         "check".to_string(),
         "--no-cache".to_string(),
+        "--isolated".to_string(),
         format!("@{}", &input_file_path.display()),
     ];
 

crates/ruff_linter/src/settings/mod.rs

@@ -44,7 +44,7 @@ pub struct CliSettings {
     pub cache_dir: PathBuf,
     pub fix: bool,
     pub fix_only: bool,
-    pub format: SerializationFormat,
+    pub output_format: SerializationFormat,
     pub show_fixes: bool,
     pub show_source: bool,
 }

crates/ruff_wasm/src/lib.rs

@@ -145,7 +145,7 @@ impl Workspace {
             fix_only: None,
             fixable: None,
             force_exclude: None,
-            format: None,
+            output_format: None,
             ignore_init_module_imports: None,
             include: None,
             logger_objects: None,

crates/ruff_workspace/src/configuration.rs

@@ -66,7 +66,7 @@ pub struct Configuration {
     pub fix: Option<bool>,
     pub fix_only: Option<bool>,
     pub force_exclude: Option<bool>,
-    pub format: Option<SerializationFormat>,
+    pub output_format: Option<SerializationFormat>,
     pub ignore_init_module_imports: Option<bool>,
     pub include: Option<Vec<FilePattern>>,
     pub line_length: Option<LineLength>,
@@ -119,7 +119,7 @@ impl Configuration {
                     .unwrap_or_else(|| cache_dir(project_root)),
                 fix: self.fix.unwrap_or(false),
                 fix_only: self.fix_only.unwrap_or(false),
-                format: self.format.unwrap_or_default(),
+                output_format: self.output_format.unwrap_or_default(),
                 show_fixes: self.show_fixes.unwrap_or(false),
                 show_source: self.show_source.unwrap_or(false),
             },
@@ -376,7 +376,7 @@ impl Configuration {
             external: options.external,
             fix: options.fix,
             fix_only: options.fix_only,
-            format: options.format,
+            output_format: options.output_format.or(options.format),
             force_exclude: options.force_exclude,
             ignore_init_module_imports: options.ignore_init_module_imports,
             include: options.include.map(|paths| {
@@ -708,7 +708,7 @@ impl Configuration {
             external: self.external.or(config.external),
             fix: self.fix.or(config.fix),
             fix_only: self.fix_only.or(config.fix_only),
-            format: self.format.or(config.format),
+            output_format: self.output_format.or(config.output_format),
             force_exclude: self.force_exclude.or(config.force_exclude),
             include: self.include.or(config.include),
             ignore_init_module_imports: self

crates/ruff_workspace/src/options.rs

@@ -236,20 +236,33 @@ pub struct Options {
     /// A list of rule codes or prefixes to consider autofixable. By default,
     /// all rules are considered autofixable.
     pub fixable: Option<Vec<RuleSelector>>,
-    #[option(
+
-        default = r#""text""#,
-        value_type = r#""text" | "json" | "junit" | "github" | "gitlab" | "pylint" | "azure""#,
-        example = r#"
-            # Group violations by containing file.
-            format = "grouped"
-        "#
-    )]
     /// The style in which violation messages should be formatted: `"text"`
     /// (default), `"grouped"` (group messages by file), `"json"`
     /// (machine-readable), `"junit"` (machine-readable XML), `"github"` (GitHub
     /// Actions annotations), `"gitlab"` (GitLab CI code quality report),
     /// `"pylint"` (Pylint text format) or `"azure"` (Azure Pipeline logging commands).
+    ///
+    /// This option has been **deprecated** in favor of `output-format`
+    /// to avoid ambiguity with Ruff's upcoming formatter.
+    #[cfg_attr(feature = "schemars", schemars(skip))]
     pub format: Option<SerializationFormat>,
+
+    /// The style in which violation messages should be formatted: `"text"`
+    /// (default), `"grouped"` (group messages by file), `"json"`
+    /// (machine-readable), `"junit"` (machine-readable XML), `"github"` (GitHub
+    /// Actions annotations), `"gitlab"` (GitLab CI code quality report),
+    /// `"pylint"` (Pylint text format) or `"azure"` (Azure Pipeline logging commands).
+    #[option(
+        default = r#""text""#,
+        value_type = r#""text" | "json" | "junit" | "github" | "gitlab" | "pylint" | "azure""#,
+        example = r#"
+            # Group violations by containing file.
+            output-format = "grouped"
+        "#
+    )]
+    pub output_format: Option<SerializationFormat>,
+
     #[option(
         default = r#"false"#,
         value_type = "bool",

crates/ruff_workspace/src/resolver.rs

@@ -13,9 +13,9 @@ use log::debug;
 use path_absolutize::path_dedot;
 use rustc_hash::{FxHashMap, FxHashSet};
 
-use ruff_linter::fs;
 use ruff_linter::packaging::is_package;
 use ruff_linter::settings::{AllSettings, Settings};
+use ruff_linter::{fs, warn_user_once};
 
 use crate::configuration::Configuration;
 use crate::pyproject;
@@ -221,6 +221,11 @@ fn resolve_configuration(
         // Resolve the current path.
         let options = pyproject::load_options(&path)
             .map_err(|err| anyhow!("Failed to parse `{}`: {}", path.display(), err))?;
+
+        if options.format.is_some() {
+            warn_user_once!("The option `format` has been deprecated to avoid ambiguity with Ruff's upcoming formatter. Use `format-output` instead.");
+        }
+
         let project_root = relativity.resolve(&path);
         let configuration = Configuration::from_options(options, &project_root)?;
 

docs/configuration.md

@@ -206,8 +206,8 @@ Options:
           Fix any fixable lint violations, but don't report on leftover violations. Implies `--fix`. Use `--no-fix-only` to disable
       --ignore-noqa
           Ignore any `# noqa` comments
-      --format <FORMAT>
+      --output-format <OUTPUT_FORMAT>
-          Output serialization format for violations [env: RUFF_FORMAT=] [possible values: text, json, json-lines, junit, grouped, github, gitlab, pylint, azure]
+          Output serialization format for violations [env: RUFF_OUTPUT_FORMAT=] [possible values: text, json, json-lines, junit, grouped, github, gitlab, pylint, azure]
   -o, --output-file <OUTPUT_FILE>
           Specify file to write the linter output to (default: stdout)
       --target-version <TARGET_VERSION>

ruff.schema.json

@@ -326,17 +326,6 @@
         "null"
       ]
     },
-    "format": {
-      "description": "The style in which violation messages should be formatted: `\"text\"` (default), `\"grouped\"` (group messages by file), `\"json\"` (machine-readable), `\"junit\"` (machine-readable XML), `\"github\"` (GitHub Actions annotations), `\"gitlab\"` (GitLab CI code quality report), `\"pylint\"` (Pylint text format) or `\"azure\"` (Azure Pipeline logging commands).",
-      "anyOf": [
-        {
-          "$ref": "#/definitions/SerializationFormat"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
     "ignore": {
       "description": "A list of rule codes or prefixes to ignore. Prefixes can specify exact rules (like `F841`), entire categories (like `F`), or anything in between.\n\nWhen breaking ties between enabled and disabled rules (via `select` and `ignore`, respectively), more specific prefixes override less specific prefixes.",
       "type": [
@@ -419,6 +408,17 @@
         "type": "string"
       }
     },
+    "output-format": {
+      "description": "The style in which violation messages should be formatted: `\"text\"` (default), `\"grouped\"` (group messages by file), `\"json\"` (machine-readable), `\"junit\"` (machine-readable XML), `\"github\"` (GitHub Actions annotations), `\"gitlab\"` (GitLab CI code quality report), `\"pylint\"` (Pylint text format) or `\"azure\"` (Azure Pipeline logging commands).",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/SerializationFormat"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "pep8-naming": {
       "description": "Options for the `pep8-naming` plugin.",
       "anyOf": [