docs(cookbook): Provide example of --color[=WHEN]

examples/git-derive.md

@@ -127,7 +127,7 @@ Last argument:
 $ git-derive diff --help
 Compare two commits
 
-Usage: git-derive[EXE] diff [COMMIT] [COMMIT] [-- <PATH>]
+Usage: git-derive[EXE] diff [OPTIONS] [COMMIT] [COMMIT] [-- <PATH>]
 
 Arguments:
   [COMMIT]  
@@ -135,18 +135,25 @@ Arguments:
   [PATH]    
 
 Options:
-  -h, --help  Print help information
+      --color[=<WHEN>]  [default: auto] [possible values: always, auto, never]
+  -h, --help            Print help information
 
 $ git-derive diff
-Diffing stage..worktree 
+Diffing stage..worktree  (color=auto)
 
 $ git-derive diff ./src
-Diffing stage..worktree ./src
+Diffing stage..worktree ./src (color=auto)
 
 $ git-derive diff HEAD ./src
-Diffing HEAD..worktree ./src
+Diffing HEAD..worktree ./src (color=auto)
 
 $ git-derive diff HEAD~~ -- HEAD
-Diffing HEAD~~..worktree HEAD
+Diffing HEAD~~..worktree HEAD (color=auto)
+
+$ git-derive diff --color
+Diffing stage..worktree  (color=always)
+
+$ git-derive diff --color=never
+Diffing stage..worktree  (color=never)
 
 ```

examples/git-derive.rs

@@ -2,7 +2,7 @@ use std::ffi::OsStr;
 use std::ffi::OsString;
 use std::path::PathBuf;
 
-use clap::{Args, Parser, Subcommand};
+use clap::{Args, Parser, Subcommand, ValueEnum};
 
 /// A fictional versioning CLI
 #[derive(Debug, Parser)] // requires `derive` feature
@@ -29,6 +29,16 @@ enum Commands {
         head: Option<OsString>,
         #[arg(last = true)]
         path: Option<OsString>,
+        #[arg(
+            long,
+            require_equals = true,
+            value_name = "WHEN",
+            num_args = 0..=1,
+            default_value_t = ColorWhen::Auto,
+            default_missing_value = "always",
+            value_enum
+        )]
+        color: ColorWhen,
     },
     /// pushes things
     #[command(arg_required_else_help = true)]
@@ -48,6 +58,22 @@ enum Commands {
     External(Vec<OsString>),
 }
 
+#[derive(ValueEnum, Copy, Clone, Debug, PartialEq, Eq)]
+enum ColorWhen {
+    Always,
+    Auto,
+    Never,
+}
+
+impl std::fmt::Display for ColorWhen {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.to_possible_value()
+            .expect("no values are skipped")
+            .get_name()
+            .fmt(f)
+    }
+}
+
 #[derive(Debug, Args)]
 #[command(args_conflicts_with_subcommands = true)]
 struct Stash {
@@ -82,6 +108,7 @@ fn main() {
             mut base,
             mut head,
             mut path,
+            color,
         } => {
             if path.is_none() {
                 path = head;
@@ -100,7 +127,13 @@ fn main() {
                 .map(|s| s.to_str().unwrap())
                 .unwrap_or("worktree");
             let path = path.as_deref().unwrap_or_else(|| OsStr::new(""));
-            println!("Diffing {}..{} {}", base, head, path.to_string_lossy());
+            println!(
+                "Diffing {}..{} {} (color={})",
+                base,
+                head,
+                path.to_string_lossy(),
+                color
+            );
         }
         Commands::Push { remote } => {
             println!("Pushing to {}", remote);

examples/git.md

@@ -125,7 +125,7 @@ Last argument:
 $ git diff --help
 Compare two commits
 
-Usage: git[EXE] diff [COMMIT] [COMMIT] [-- <PATH>]
+Usage: git[EXE] diff [OPTIONS] [COMMIT] [COMMIT] [-- <PATH>]
 
 Arguments:
   [COMMIT]  
@@ -133,18 +133,25 @@ Arguments:
   [PATH]    
 
 Options:
-  -h, --help  Print help information
+      --color[=<WHEN>]  [default: auto] [possible values: always, auto, never]
+  -h, --help            Print help information
 
 $ git diff
-Diffing stage..worktree 
+Diffing stage..worktree  (color=auto)
 
 $ git diff ./src
-Diffing stage..worktree ./src
+Diffing stage..worktree ./src (color=auto)
 
 $ git diff HEAD ./src
-Diffing HEAD..worktree ./src
+Diffing HEAD..worktree ./src (color=auto)
 
 $ git diff HEAD~~ -- HEAD
-Diffing HEAD~~..worktree HEAD
+Diffing HEAD~~..worktree HEAD (color=auto)
+
+$ git diff --color
+Diffing stage..worktree  (color=always)
+
+$ git diff --color=never
+Diffing stage..worktree  (color=never)
 
 ```

examples/git.rs

@@ -20,7 +20,15 @@ fn cli() -> Command {
                 .about("Compare two commits")
                 .arg(arg!(base: [COMMIT]))
                 .arg(arg!(head: [COMMIT]))
-                .arg(arg!(path: [PATH]).last(true)),
+                .arg(arg!(path: [PATH]).last(true))
+                .arg(
+                    arg!(--color <WHEN>)
+                        .value_parser(["always", "auto", "never"])
+                        .num_args(0..=1)
+                        .require_equals(true)
+                        .default_value("auto")
+                        .default_missing_value("always"),
+                ),
         )
         .subcommand(
             Command::new("push")
@@ -59,6 +67,11 @@ fn main() {
             );
         }
         Some(("diff", sub_matches)) => {
+            let color = sub_matches
+                .get_one::<String>("color")
+                .map(|s| s.as_str())
+                .expect("defaulted in clap");
+
             let mut base = sub_matches.get_one::<String>("base").map(|s| s.as_str());
             let mut head = sub_matches.get_one::<String>("head").map(|s| s.as_str());
             let mut path = sub_matches.get_one::<String>("path").map(|s| s.as_str());
@@ -73,7 +86,7 @@ fn main() {
             let base = base.unwrap_or("stage");
             let head = head.unwrap_or("worktree");
             let path = path.unwrap_or("");
-            println!("Diffing {}..{} {}", base, head, path);
+            println!("Diffing {}..{} {} (color={})", base, head, path, color);
         }
         Some(("push", sub_matches)) => {
             println!(