- Add support for captuing --help when using catch_all

Author: DannyBen

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "September 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "November 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% September 2025
+% November 2025
 
 NAME
 ==================================================

lib/bashly/config_validator.rb

@@ -35,6 +35,7 @@ def assert_catch_all_hash(key, value)
       assert_string "#{key}.label", value['label']
       assert_optional_string "#{key}.help", value['help']
       assert_boolean "#{key}.required", value['required']
+      assert_boolean "#{key}.catch_help", value['catch_help']
     end
 
     def assert_default_command(key, value)

lib/bashly/script/catch_all.rb

@@ -3,7 +3,7 @@ module Script
     class CatchAll
       class << self
         def option_keys
-          @option_keys ||= %i[label help required]
+          @option_keys ||= %i[label help required catch_help]
         end
 
         def from_config(config)
@@ -13,7 +13,7 @@ def from_config(config)
           when String
             { label: config }
           when Hash
-            { label: config['label'], help: config['help'], required: config['required'] }
+            config.transform_keys(&:to_sym).slice(*option_keys)
           else
             {}
           end
@@ -22,11 +22,12 @@ def from_config(config)
         end
       end
 
-      def initialize(label: nil, help: nil, required: false, enabled: true)
+      def initialize(label: nil, help: nil, required: false, catch_help: false, enabled: true)
         @label = label
         @help = help
         @required = required
         @enabled = enabled
+        @catch_help = catch_help
       end
 
       def enabled?
@@ -45,6 +46,10 @@ def required?
         @required
       end
 
+      def catch_help?
+        @catch_help
+      end
+
       def usage_string
         return nil unless enabled?
 

lib/bashly/script/introspection/flags.rb

@@ -16,6 +16,13 @@ def flags
           end
         end
 
+        # Returns true if there is at least one fixed flag (--version / --help)
+        # Root command always has --version and subcommands always have --help
+        # except when it is consumed by catch_all
+        def fixed_flags?
+          root_command? || !catch_all.catch_help?
+        end
+
         # Returns true if this command's flags should be considered as gloal
         # flags, and cascade to subcommands
         def global_flags?

lib/bashly/views/command/fixed_flags_filter.gtx

@@ -12,12 +12,14 @@ if root_command?
   > 
 end
 
-= (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
->       long_usage=yes
->       <%= function_name %>_usage
->       exit
->       ;;
-> 
+unless catch_all.catch_help?
+  = (short_flag_exist?("-h") ? "--help)" : "--help | -h)").indent(4)
+  >       long_usage=yes
+  >       <%= function_name %>_usage
+  >       exit
+  >       ;;
+  > 
+end
 
 if global_flags?
   flags.each do |flag|

lib/bashly/views/command/long_usage.gtx

@@ -1,15 +1,7 @@
 = view_marker
 
 > if [[ -n "$long_usage" ]]; then
-options_caption = strings[:options]
-if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
-  options_caption = strings[:global_options]
-end
-
->   printf "%s\n" "{{ options_caption.color(:caption) }}"
->
-= render(:usage_flags).indent 2 if flags.any?
-= render(:usage_fixed_flags).indent 2
+= render(:usage_options).indent 2
 = render(:usage_args).indent 2 if args.any? or catch_all.help
 = render(:usage_environment_variables).indent 2 if environment_variables.any?
 = render(:usage_examples).indent 2 if examples

lib/bashly/views/command/usage_fixed_flags.gtx

@@ -1,13 +1,15 @@
 = view_marker
 
-if short_flag_exist?("-h")
-  > printf "  %s\n" "{{ '--help'.color(:flag) }}"
-else
-  > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
-end
+unless catch_all.catch_help?
+  if short_flag_exist?("-h")
+    > printf "  %s\n" "{{ '--help'.color(:flag) }}"
+  else
+    > printf "  %s\n" "{{ '--help, -h'.color(:flag) }}"
+  end
 
-> printf "    {{ strings[:help_flag_text] }}\n"
-> echo
+  > printf "    {{ strings[:help_flag_text] }}\n"
+  > echo
+end
 
 if root_command?
   if short_flag_exist?("-v")

lib/bashly/views/command/usage_options.gtx

@@ -0,0 +1,13 @@
+= view_marker
+
+if flags.any? || fixed_flags?
+  options_caption = strings[:options]
+  if commands.any? && (public_flags.any? || (flags.any? && Settings.private_reveal_key))
+    options_caption = strings[:global_options]
+  end
+
+  >   printf "%s\n" "{{ options_caption.color(:caption) }}"
+  >
+  = render(:usage_flags).indent 2 if flags.any?
+  = render(:usage_fixed_flags).indent 2
+end

spec/approvals/fixtures/catch-all-including-help

@@ -0,0 +1,26 @@
++ bundle exec bashly generate
+creating user files in src
+skipped src/docker_command.sh (exists)
+created ./cli
+run ./cli --help to test your bash script
++ ./cli docker --help
+args: none
+
+other_args:
+- ${other_args[*]} = --help
+- ${other_args[0]} = --help
++ ./cli docker --show-help-anyway
+cli docker - Pass all arguments to the docker cli
+
+Usage:
+  cli docker [OPTIONS] [--] [PARAMS...]
+  cli docker --help | -h
+
+Options:
+  --show-help-anyway
+    Show this help message
+
+Arguments:
+  PARAMS...
+    Parameters to pass to docker
+