From 9f3df0d5a8fffd72d89bac820d10e4f550c352fc Mon Sep 17 00:00:00 2001
From: ychampion <ychampion@users.noreply.github.com>
Date: Fri, 10 Jul 2026 21:39:54 +0000
Subject: [PATCH] fix(options): preserve pre-clap color compatibility

Restore the hidden value and option aliases lost during the clap migration while keeping canonical names in help output.

Fixes: #1863

Constraint: Preserve command lines accepted before v0.23.5 without changing canonical help output.
Rejected: Add visible aliases to help | Legacy spellings should remain compatibility-only.
Confidence: high
Scope-risk: narrow
Directive: Keep these aliases hidden unless the public CLI documentation intentionally changes.
Tested: cargo test; cargo clippy --all-targets -- -D warnings; cargo fmt --all -- --check; parser regressions; CLI smoke tests.
Not-tested: nix flake check (Nix is unavailable in this environment).
---
 src/options/parser.rs | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/src/options/parser.rs b/src/options/parser.rs
index 5e8ba7da7..fbd2d6fe3 100644
--- a/src/options/parser.rs
+++ b/src/options/parser.rs
@@ -79,11 +79,13 @@ pub fn get_command() -> clap::Command {
             .default_missing_value("auto")
             .default_value("auto"))
         .arg(arg!(--"color-scale" <FIELDS> "highlight value of FIELDS distinctly")
+            .alias("colour-scale")
             .num_args(0..)
             .value_parser(value_parser!(ColorScaleArgs))
             .default_missing_value("all")
             .value_delimiter(','))
         .arg(arg!(--"color-scale-mode" <MODE> "mode for --color-scale")
+            .alias("colour-scale-mode")
             .num_args(1)
             .value_parser(value_parser!(ColorScaleModeArgs))
             .default_value("gradient"))
@@ -180,14 +182,11 @@ impl ValueEnum for ShowWhen {
     }
 
     fn to_possible_value(&self) -> Option<clap::builder::PossibleValue> {
-        Some(
-            match self {
-                Self::Always => "always",
-                Self::Auto => "auto",
-                Self::Never => "never",
-            }
-            .into(),
-        )
+        Some(match self {
+            Self::Always => PossibleValue::new("always"),
+            Self::Auto => PossibleValue::new("auto").alias("automatic"),
+            Self::Never => PossibleValue::new("never"),
+        })
     }
 
     fn from_str(s: &str, _ignore_case: bool) -> Result<Self, String> {
@@ -357,6 +356,27 @@ pub mod test {
         get_command().no_binary_name(true).try_get_matches_from(itr)
     }
 
+    #[test]
+    fn accepts_automatic_color_value() {
+        let cli = mock_cli_try(["--color=automatic"]).unwrap();
+        assert_eq!(cli.get_one::<ShowWhen>("color"), Some(&ShowWhen::Auto));
+    }
+
+    #[test]
+    fn accepts_colour_scale_aliases() {
+        let cli = mock_cli_try(["--colour-scale=size", "--colour-scale-mode=fixed"]).unwrap();
+        assert_eq!(
+            cli.get_many::<ColorScaleArgs>("color-scale")
+                .unwrap()
+                .collect::<Vec<_>>(),
+            [&ColorScaleArgs::Size]
+        );
+        assert_eq!(
+            cli.get_one::<ColorScaleModeArgs>("color-scale-mode"),
+            Some(&ColorScaleModeArgs::Fixed)
+        );
+    }
+
     #[test]
     fn deduce_files() {
         let cli = mock_cli(vec!["file1", "file2"]);