new HelpOption: Allow full subcommand flag display

_examples/shell/optionalflags/main.go

@@ -0,0 +1,31 @@
+package main
+
+import (
+	"github.com/alecthomas/kong"
+)
+
+var cli struct {
+	DryRun    string `help:"optional dry run flag"`
+	Mandatory bool   `required:"" help:"mandatory global flag"`
+	Resource  struct {
+		Create struct {
+			Name string `required:"" help:"name of the resource"`
+		} `cmd:"" help:"create a resource"`
+		Delete struct {
+			Scope   string   `required:"" help:"mandatory subcommand flag"`
+			Labels  []string `help:"labels to match when deleting"`
+			Version string   `help:"version to match when deleting"`
+		} `cmd:"" help:"delete resource(s)"`
+	} `cmd:"" help:"operate on resources"`
+}
+
+func main() {
+	ctx := kong.Parse(&cli,
+		kong.Name("help"),
+		kong.Description("An app demonstrating SubcommandsWithOptionalFlags"),
+		kong.UsageOnError(),
+		kong.ConfigureHelp(kong.HelpOptions{
+			SubcommandsWithOptionalFlags: true,
+		}))
+	ctx.Run()
+}

build.go

@@ -281,6 +281,7 @@ func buildField(k *Kong, node *Node, v reflect.Value, ft reflect.StructField, fv
 		Mapper:       mapper,
 		Tag:          tag,
 		Target:       fv,
+		Parent:       node,
 		Enum:         tag.Enum,
 		Passthrough:  tag.Passthrough,
 

help.go

@@ -52,6 +52,11 @@ type HelpOptions struct {
 	// Don't show the help associated with subcommands
 	NoExpandSubcommands bool
 
+	// Whether to include optional flags in command summaries
+	// If true, command summaries will include flags not marked as required
+	// If false (the default), command summaries will only show required flags
+	SubcommandsWithOptionalFlags bool
+
 	// Clamp the help wrap width to a value smaller than the terminal width.
 	// If this is set to a non-positive number, the terminal width is used; otherwise,
 	// the min of this value or the terminal width is used.
@@ -356,7 +361,7 @@ func collectCommandGroups(nodes []*Node) []helpCommandGroup {
 }
 
 func printCommandSummary(w *helpWriter, cmd *Command) {
-	w.Print(cmd.Summary())
+	w.Print(cmd.SummaryWithOptions(w.HelpOptions.SubcommandsWithOptionalFlags))
 	if cmd.Help != "" {
 		w.Indent().Wrap(cmd.Help)
 	}

help_test.go

@@ -373,6 +373,63 @@ Commands:
 	})
 }
 
+// Tests HelpOptions.SubcommandsWithOptionalFlags
+//
+// MUST retain original behaviour by default (see "default" sub test)
+// MUST show optional subcommand flags when SubcommandsWithOptionalFlags
+//
+//	is enabled (see "forced" sub test)
+//
+// MUST show any _required_ parent flags on subcommands
+// MUST NOT show any optional parent flags on subcommands
+func TestSubcommandsWithOptionalFlags(t *testing.T) {
+	var cli struct {
+		Sub struct {
+			ParentFlag string `help:"I should only appear on parent"`
+			Mandatory  string `required:"" help:"I should appear on all sub commands"`
+			MoreSub    struct {
+				Flag     string `help:"A flag."`
+				Required string `required:"" help:"A required flag."`
+			} `cmd help:"more sub help"`
+			Another struct {
+			} `cmd help:"another help"`
+		} `cmd help:"sub help"`
+	}
+	w := bytes.NewBuffer(nil)
+
+	app := mustNew(t, &cli,
+		kong.Name("test-app"),
+		kong.Description("A test app."),
+		kong.Writers(w, w),
+		kong.Exit(func(int) {}),
+	)
+
+	// Default: don't show flags on nested items unless they are `required`
+	t.Run("default", func(t *testing.T) {
+		expected := "Usage: test-app <command>\n\nA test app.\n\nFlags:\n  -h, --help    Show context-sensitive help.\n\nCommands:\n  sub more-sub --mandatory=STRING --required=STRING\n    more sub help\n\n  sub another --mandatory=STRING\n    another help\n\nRun \"test-app <command> --help\" for more information on a command.\n"
+		_, _ = app.Parse([]string{"--help"})
+		assert.Equal(t, expected, w.String())
+	})
+
+	w.Truncate(0)
+	app = mustNew(t, &cli,
+		kong.Name("test-app"),
+		kong.Description("A test app."),
+		kong.Writers(w, w),
+		kong.HelpOptions{
+			SubcommandsWithOptionalFlags: true,
+		},
+		kong.Exit(func(int) {}),
+	)
+
+	// Force flag display: don't show flags on nested items unless they are `required`
+	t.Run("forced", func(t *testing.T) {
+		expected := "Usage: test-app <command>\n\nA test app.\n\nFlags:\n  -h, --help    Show context-sensitive help.\n\nCommands:\n  sub more-sub --mandatory=STRING --required=STRING [--flag=STRING]\n    more sub help\n\n  sub another --mandatory=STRING\n    another help\n\nRun \"test-app <command> --help\" for more information on a command.\n"
+		_, _ = app.Parse([]string{"--help"})
+		assert.Equal(t, expected, w.String())
+	})
+}
+
 func TestHelpCompactNoExpand(t *testing.T) {
 	var cli struct {
 		One struct {

model.go

@@ -141,10 +141,25 @@ func (n *Node) Depth() int {
 	return depth
 }
 
-// Summary help string for the node (not including application name).
-func (n *Node) Summary() string {
+// SummaryWithOptions help string for the node (not including application name)
+//
+// Used both by help writing as well as other parts of the application
+//
+// Most cases just use Summary() (default settings)
+//
+// The help printer uses this optional version to pass options along.
+//
+// if includeOptionalFlags is true, all flags for a command will
+// be included. see HelpOptions.IncludeOptionalFlagsInSummary
+func (n *Node) SummaryWithOptions(includeOptionalFlags bool) string {
 	summary := n.Path()
-	if flags := n.FlagSummary(true); flags != "" {
+	var flags string
+	if includeOptionalFlags {
+		flags = n.FlagSummaryWithOptions(true)
+	} else {
+		flags = n.FlagSummary(true)
+	}
+	if flags != "" {
 		summary += " " + flags
 	}
 	args := []string{}
@@ -175,6 +190,12 @@ func (n *Node) Summary() string {
 	return summary
 }
 
+// Summary help string for the node (not including application name).
+// Default behaviour used throughout the application
+func (n *Node) Summary() string {
+	return n.SummaryWithOptions(false)
+}
+
 // FlagSummary for the node.
 func (n *Node) FlagSummary(hide bool) string {
 	required := []string{}
@@ -190,6 +211,31 @@ func (n *Node) FlagSummary(hide bool) string {
 	return strings.Join(required, " ")
 }
 
+// FlagSummaryWithOptions is the same behaviour as FlagSummary but
+// also includes any optional flags associated with the Node
+func (n *Node) FlagSummaryWithOptions(hide bool) string {
+	required := []string{}
+	optional := []string{}
+	count := 0
+	for _, group := range n.AllFlags(hide) {
+		for _, flag := range group {
+			count++
+			// Show required flags
+			if flag.Required {
+				required = append(required, flag.Summary())
+			} else if flag.Parent == n {
+				// Show optional flags _if they belong to us_
+				optional = append(optional, flag.Summary())
+			}
+		}
+	}
+	if len(optional) > 0 {
+		// Group optional flags together and surround with brackets
+		required = append(required, fmt.Sprintf("[%s]", strings.Join(optional, " ")))
+	}
+	return strings.Join(required, " ")
+}
+
 // FullPath is like Path() but includes the Application root node.
 func (n *Node) FullPath() string {
 	root := n
@@ -250,6 +296,7 @@ type Value struct {
 	Mapper       Mapper
 	Tag          *Tag
 	Target       reflect.Value
+	Parent       *Node
 	Required     bool
 	Set          bool   // Set to true when this value is set through some mechanism.
 	Format       string // Formatting directive, if applicable.