Update help, man page and completions

assets/completions/bat.bash.in

@@ -112,7 +112,12 @@ _bat() {
 		COMPREPLY=($(compgen -c -- "$cur"))
 		return 0
 		;;
-	--theme | \
+	--theme)
+    	local IFS=$'\n'
+    	COMPREPLY=($(compgen -W "auto${IFS}auto:always${IFS}auto:system${IFS}dark${IFS}light${IFS}$("$1" --list-themes)" -- "$cur"))
+                    __bat_escape_completions
+    	return 0
+    	;;
 	--theme-dark | \
 	--theme-light)
 		local IFS=$'\n'

assets/completions/bat.fish.in

@@ -129,6 +129,14 @@ set -l tabs_opts '
     8\t
 '
 
+set -l special_themes '
+    auto\tdefault,\ Choose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    auto:always\tChoose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    auto:system\tChoose\ a\ theme\ based\ on\ dark\ or\ light\ mode
+    dark\tUse\ the\ theme\ specified\ by\ --theme-dark
+    light\tUse\ the\ theme\ specified\ by\ --theme-light
+'
+
 # Completions:
 
 complete -c $bat -l acknowledgements -d "Print acknowledgements" -n __fish_is_first_arg
@@ -203,7 +211,7 @@ complete -c $bat -l tabs -x -a "$tabs_opts" -d "Set tab width" -n __bat_no_excl_
 
 complete -c $bat -l terminal-width -x -d "Set terminal <width>, +<offset>, or -<offset>" -n __bat_no_excl_args
 
-complete -c $bat -l theme -x -a "(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme" -n __bat_no_excl_args
+complete -c $bat -l theme -x -a "$special_themes(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme" -n __bat_no_excl_args
 
 complete -c $bat -l theme-dark -x -a "(command $bat --list-themes | command cat)" -d "Set the syntax highlighting theme for dark backgrounds" -n __bat_no_excl_args
 

assets/completions/bat.zsh.in

@@ -42,7 +42,7 @@ _{{PROJECT_EXECUTABLE}}_main() {
         --decorations='[specify when to show the decorations]:when:(auto never always)'
         --paging='[specify when to use the pager]:when:(auto never always)'
         '(-m --map-syntax)'{-m+,--map-syntax=}'[map a glob pattern to an existing syntax name]: :->syntax-maps'
-        '(--theme)'--theme='[set the color theme for syntax highlighting]:theme:->themes'
+        '(--theme)'--theme='[set the color theme for syntax highlighting]:theme:->theme_preferences'
         '(--theme-dark)'--theme-dark='[set the color theme for syntax highlighting for dark backgrounds]:theme:->themes'
         '(--theme-light)'--theme-light='[set the color theme for syntax highlighting for light backgrounds]:theme:->themes'
         '(: --list-themes --list-languages -L)'--list-themes'[show all supported highlighting themes]'
@@ -84,7 +84,13 @@ _{{PROJECT_EXECUTABLE}}_main() {
 
         themes)
             local -a themes expl
-            themes=( ${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
+            themes=(${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
+
+            _wanted themes expl 'theme' compadd -a themes && ret=0
+        ;;
+        theme_preferences)
+            local -a themes expl
+            themes=(auto dark light auto:always auto:system ${(f)"$(_call_program themes {{PROJECT_EXECUTABLE}} --list-themes)"} )
 
             _wanted themes expl 'theme' compadd -a themes && ret=0
         ;;

assets/manual/bat.1.in

@@ -155,20 +155,35 @@ will use JSON syntax, and ignore '.dev'
 Set the theme for syntax highlighting. Use \fB\-\-list\-themes\fP to see all available themes.
 To set a default theme, add the \fB\-\-theme="..."\fP option to the configuration file or
 export the \fBBAT_THEME\fP environment variable (e.g.: \fBexport BAT_THEME="..."\fP).
+
+Special values:
+.RS
+.IP "auto (\fIdefault\fR)"
+Picks a dark or light theme depending on the terminal's colors.
+Use \fB-\-theme\-light\fR and \fB-\-theme\-dark\fR to customize the selected theme.
+.IP "auto:always"
+Variation of \fBauto\fR where where the terminal's colors are detected even when the output is redirected.
+.IP "auto:system (macOS only)"
+Variation of \fBauto\fR where the color scheme is detected from the system-wide preference instead.
+.IP "dark"
+Use the dark theme specified by \fB-\-theme-dark\fR.
+.IP "light"
+Use the light theme specified by \fB-\-theme-light\fR.
+.RE
 .HP
 \fB\-\-theme\-dark\fR <theme>
 .IP
 Sets the theme name for syntax highlighting used when the terminal uses a dark background.
 To set a default theme, add the \fB\-\-theme-dark="..."\fP option to the configuration file or
 export the \fBBAT_THEME_DARK\fP environment variable (e.g. \fBexport BAT_THEME_DARK="..."\fP).
-This option is ignored if \fB\-\-theme\fP option is set.
+This option only has an effect when \fB\-\-theme\fP option is set to \fBauto\fR or \fBdark\fR.
 .HP
 \fB\-\-theme\-light\fR <theme>
 .IP
 Sets the theme name for syntax highlighting used when the terminal uses a dark background.
 To set a default theme, add the \fB\-\-theme-dark="..."\fP option to the configuration file or
 export the \fBBAT_THEME_LIGHT\fP environment variable (e.g. \fBexport BAT_THEME_LIGHT="..."\fP).
-This option is ignored if \fB\-\-theme\fP option is set.
+This option only has an effect when \fB\-\-theme\fP option is set to \fBauto\fR or \fBlight\fR.
 .HP
 \fB\-\-list\-themes\fR
 .IP

doc/long-help.txt

@@ -109,10 +109,18 @@ Options:
             'bat --ignored-suffix ".dev" my_file.json.dev' will use JSON syntax, and ignore '.dev'
 
       --theme <theme>
-          Set the theme for syntax highlighting. Note that this option overrides '--theme-dark' and
-          '--theme-light'. Use '--list-themes' to see all available themes. To set a default theme,
-          add the '--theme="..."' option to the configuration file or export the BAT_THEME
-          environment variable (e.g.: export BAT_THEME="...").
+          Set the theme for syntax highlighting. Use '--list-themes' to see all available themes. To
+          set a default theme, add the '--theme="..."' option to the configuration file or export
+          the BAT_THEME environment variable (e.g.: export BAT_THEME="...").
+
+          Special values:
+
+            * auto: Picks a dark or light theme depending on the terminal's colors (default).
+                    Use '--theme-light' and '--theme-dark' to customize the selected theme.
+              * auto:always: Detect the terminal's colors even when the output is redirected.
+              * auto:system: Detect the color scheme from the system-wide preference (macOS only).
+            * dark: Use the dark theme specified by '--theme-dark'.
+            * light: Use the light theme specified by '--theme-light'.
 
       --theme-light <theme>
           Sets the theme name for syntax highlighting used when the terminal uses a light

src/bin/bat/clap_app.rs

@@ -375,12 +375,18 @@ pub fn build_app(interactive_output: bool) -> Command {
                 .overrides_with("theme")
                 .help("Set the color theme for syntax highlighting.")
                 .long_help(
-                    "Set the theme for syntax highlighting. Note that this option overrides \
-                    '--theme-dark' and '--theme-light'. Use '--list-themes' to \
+                    "Set the theme for syntax highlighting. Use '--list-themes' to \
                      see all available themes. To set a default theme, add the \
                      '--theme=\"...\"' option to the configuration file or export the \
                      BAT_THEME environment variable (e.g.: export \
-                     BAT_THEME=\"...\").",
+                     BAT_THEME=\"...\").\n\n\
+                     Special values:\n\n  \
+                     * auto: Picks a dark or light theme depending on the terminal's colors (default).\n          \
+                     Use '--theme-light' and '--theme-dark' to customize the selected theme.\n    \
+                     * auto:always: Detect the terminal's colors even when the output is redirected.\n    \
+                     * auto:system: Detect the color scheme from the system-wide preference (macOS only).\n  \
+                     * dark: Use the dark theme specified by '--theme-dark'.\n  \
+                     * light: Use the light theme specified by '--theme-light'.",
                 ),
         )
         .arg(

src/theme.rs

@@ -216,6 +216,10 @@ impl ColorSchemeDetector for TerminalColorSchemeDetector {
 
 #[cfg(not(target_os = "macos"))]
 fn color_scheme_from_system() -> Option<ColorScheme> {
+    crate::bat_warning!(
+        "Theme 'auto:system' is only supported on macOS, \
+        using default."
+    );
     None
 }