feat: add flag help groups

Issue spf13#1327

command.go

@@ -32,6 +32,7 @@ import (
 
 const (
  FlagSetByCobraAnnotation = "cobra_annotation_flag_set_by_cobra"
+ FlagHelpGroupAnnotation = "cobra_annotation_flag_help_group"
  CommandDisplayNameAnnotation = "cobra_annotation_command_display_name"
 )
 
@@ -145,6 +146,9 @@ type Command struct {
  // groups for subcommands
  commandgroups []*Group
 
+ // groups for flags in usage text.
+ flagHelpGroups []*Group
+
  // args is actual args parsed from flags.
  args []string
  // flagErrorBuf contains all error messages from pflag.
@@ -568,13 +572,22 @@ Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help")
  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
 
 Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
- {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+ {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{$cmd := .}}{{if eq (len .FlagHelpGroups) 0}}{{if .HasAvailableLocalFlags}}
 
 Flags:
 {{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
 
 Global Flags:
-{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{else}}{{$flags := .LocalFlags}}{{range $helpGroup := .FlagHelpGroups}}{{if not (eq (len ($cmd.UsageByFlagHelpGroupID "")) 0)}}
+
+Flags:
+{{$cmd.UsageByFlagHelpGroupID "" | trimTrailingWhitespaces}}{{end}}
+
+{{.Title}} Flags:
+{{$cmd.UsageByFlagHelpGroupID $helpGroup.ID | trimTrailingWhitespaces}}{{if not (eq (len ($cmd.UsageByFlagHelpGroupID "global")) 0)}}
+
+Global Flags:
+{{$cmd.UsageByFlagHelpGroupID "global" | trimTrailingWhitespaces}}{{end}}{{end}}{{end}}{{if .HasHelpSubCommands}}
 
 Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
@@ -1336,6 +1349,80 @@ func (c *Command) Groups() []*Group {
  return c.commandgroups
 }
 
+// FlagHelpGroups returns a slice of the command's flag help groups
+func (c *Command) FlagHelpGroups() []*Group {
+ return c.flagHelpGroups
+}
+
+// AddFlagHelpGroup adds one more flag help group do the command. Returns an error if the Group.ID is empty,
+// or if the "global" reserved ID is used
+func (c *Command) AddFlagHelpGroup(groups ...*Group) error {
+ for _, group := range groups {
+ if len(group.ID) == 0 {
+ return fmt.Errorf("flag help group ID must have at least one character")
+ }
+
+ if group.ID == "global" {
+ return fmt.Errorf(`"global" is a reserved flag help group ID`)
+ }
+
+ c.flagHelpGroups = append(c.flagHelpGroups, group)
+ }
+
+ return nil
+}
+
+func (c *Command) hasFlagHelpGroup(groupID string) bool {
+ for _, g := range c.flagHelpGroups {
+ if g.ID == groupID {
+ return true
+ }
+ }
+
+ return false
+}
+
+// AddFlagToHelpGroupID adds associates a flag to a groupID. Returns an error if the flag or group is non-existent
+func (c *Command) AddFlagToHelpGroupID(flag, groupID string) error {
+ lf := c.Flags()
+
+ if !c.hasFlagHelpGroup(groupID) {
+ return fmt.Errorf("no such flag help group: %v", groupID)
+ }
+
+ err := lf.SetAnnotation(flag, FlagHelpGroupAnnotation, []string{groupID})
+ if err != nil {
+ return err
+ }
+
+ return nil
+}
+
+// UsageByFlagHelpGroupID returns the command flag's usage split by flag help groups. Flags without groups associated
+// will appear under "Flags", and inherited flags will appear under "Global Flags"
+func (c *Command) UsageByFlagHelpGroupID(groupID string) string {
+ if groupID == "global" {
+ return c.InheritedFlags().FlagUsages()
+ }
+
+ fs := &flag.FlagSet{}
+
+ c.LocalFlags().VisitAll(func(f *flag.Flag) {
+ if _, ok := f.Annotations[FlagHelpGroupAnnotation]; !ok {
+ if groupID == "" {
+ fs.AddFlag(f)
+ }
+ return
+ }
+
+ if id := f.Annotations[FlagHelpGroupAnnotation][0]; id == groupID {
+ fs.AddFlag(f)
+ }
+ })
+
+ return fs.FlagUsages()
+}
+
 // AllChildCommandsHaveGroup returns if all subcommands are assigned to a group
 func (c *Command) AllChildCommandsHaveGroup() bool {
  for _, sub := range c.commands {

command_test.go

@@ -920,6 +920,82 @@ func TestPersistentRequiredFlagsWithDisableFlagParsing(t *testing.T) {
  }
 }
 
+func TestFlagHelpGroups(t *testing.T) {
+
+ t.Run("add flag to non-existing flag help group", func(t *testing.T) {
+ rootCmd := &Command{Use: "root", Run: emptyRun}
+ b := "b"
+
+ rootCmd.Flags().Bool(b, false, "bool flag")
+
+ err := rootCmd.AddFlagToHelpGroupID(b, "id")
+ if err == nil {
+ t.Error("Expected error when adding a flag to non-existent flag help group")
+ }
+ })
+
+ t.Run("add non-existing flag to flag help group", func(t *testing.T) {
+ rootCmd := &Command{Use: "root", Run: emptyRun}
+
+ group := Group{ID: "id", Title: "GroupTitle"}
+ rootCmd.AddFlagHelpGroup(&group)
+
+ err := rootCmd.AddFlagToHelpGroupID("", "id")
+ if err == nil {
+ t.Error("Expected error when adding a non-existent flag to flag help group")
+ }
+
+ })
+
+ t.Run("add flag to flag help group", func(t *testing.T) {
+ child := &Command{Use: "child", Run: emptyRun}
+ rootCmd := &Command{Use: "root", Run: emptyRun}
+
+ rootCmd.AddCommand(child)
+
+ b := "b"
+ s := "s"
+ i := "i"
+ g := "g"
+
+ child.Flags().Bool(b, false, "bool flag")
+ child.Flags().String(s, "", "string flag")
+ child.Flags().Int(i, 0, "int flag")
+ rootCmd.PersistentFlags().String(g, "", "global flag")
+
+ group := Group{ID: "groupId", Title: "GroupTitle"}
+
+ child.AddFlagHelpGroup(&group)
+
+ _ = child.AddFlagToHelpGroupID(b, group.ID)
+ _ = child.AddFlagToHelpGroupID(s, group.ID)
+ x := `Usage:
+ root child [flags]
+
+Flags:
+ -h, --help help for child
+ --i int int flag
+
+GroupTitle Flags:
+ --b bool flag
+ --s string string flag
+
+Global Flags:
+ --g string global flag
+`
+
+ got, err := executeCommand(rootCmd, "help", "child")
+ if err != nil {
+ t.Errorf("Unexpected error: %v", err)
+ }
+
+ if got != x {
+ t.Errorf("Help text mismatch.\nExpected:\n%s\n\nGot:\n%s\n", x, got)
+ }
+ })
+
+}
+
 func TestInitHelpFlagMergesFlags(t *testing.T) {
  usage := "custom flag"
  rootCmd := &Command{Use: "root"}