feat: add flag help groups #2117

pedromotita · 2024-03-07T18:31:16Z

Description

Flags can now be split into groups in usage text:

$ root child --help

Usage:
  root child [flags]

Flags:
  -h, --help    help for child
      --i int   int flag

Grouped Flags:
      --b          bool flag
      --s string   string flag

Global Flags:
      --g string   global flag

Related Issues

Closes group flags for a subcommand #1327

Implementation Details

The API for this feature was based on this comment. Check it out :)

Issue spf13#1327

CLAassistant · 2024-03-07T18:46:04Z

All committers have signed the CLA.

paulopacitti

That's a nice addition to cobra!

paulopacitti · 2024-03-07T19:09:50Z

command.go

+			if groupID == "" {
+				fs.AddFlag(f)
+			}
+			return


Isn't return "" better than returning nil in this case?

This return statement is from VisitAll() closure. It's not actually returning any values, but working as a control flow statement, so we don't access an out of bound index at f.Annotations[FlagHelpGroupsAnnotation] bellow

you're right, my mistake! Resolving it

eiffel-fl

Hi!

Thank you for this PR, this is really appreciated!

I tested it and it works fine:

$ cat go.mod 
module github.com/eiffel-fl/group-flags-example

go 1.21.7

require github.com/spf13/cobra v1.8.0

require (
        github.com/inconshreveable/mousetrap v1.1.0 // indirect
        github.com/spf13/pflag v1.0.5 // indirect
)

replace github.com/spf13/cobra => github.com/pedromotita/cobra v0.0.0-20240307182157-e9498ae28a51
$ cat main.go 
package main

import (
        "github.com/spf13/cobra"
)

func main() {
        child := &cobra.Command{Use: "child", Run: func (*cobra.Command, []string) {}}
        rootCmd := &cobra.Command{Use: "root", Run: func (*cobra.Command, []string) {}}

        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 := cobra.Group{ID: "groupId", Title: "GroupTitle"}

        child.AddFlagHelpGroup(&group)

        _ = child.AddFlagToHelpGroupID(b, group.ID)
        _ = child.AddFlagToHelpGroupID(s, group.ID)
        rootCmd.Execute()
}%
$  go run . child --help
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

I have some small comments.

Best regards.

eiffel-fl · 2024-03-12T09:54:05Z

command.go

+			if groupID == "" {
+				fs.AddFlag(f)
+			}


I am not sure to understand why you are adding flags without group to this flag set, can you please shed some light?

This is the solution I've found for printing the usage of flags that have not been added to any flagHelpGroup.

If you see the template on Command.UsageTemplate, I use UsageByFlagHelpGroupID to print flag usages when len(c.FlagHelpGroups) != 0. But I still have to cover the case where there are flags not attached to any group, which is the case of the i flag in your example. I guarantee that there wont be any empty groupID by returning an error at AddFlagHelpGroup

The same goes for InheritedFlags and the global reserved group ID.

So, this code basically avoids having orphan flags without group.
This makes sense, thank you!

Maybe add a constant for the special empty group id?

const NoGroup = ""

eiffel-fl · 2024-03-12T10:10:31Z

command.go

+	return nil
+}
+
+func (c *Command) hasFlagHelpGroup(groupID string) bool {


Instead of ID, should you use category?

I don't understand. Do you mean renaming groupID to category?

I prefer groupID to make it clear we are dealing with Group here

I don't understand. Do you mean renaming groupID to category?

Yes.

I prefer groupID to make it clear we are dealing with Group here

Let's stick with groupID.

eiffel-fl · 2024-03-12T10:12:02Z

command.go

+
+// 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 {


I know that Group is already used in cobra, but I am wondering if we should not use Group instead of HelpGroup?

There is a previous discussion on why to use cobra's Group in this thread. Take a look 😉

I was only referring to naming here, i.e. AddFlagGroup() instead of AddFlagHelperGroup().

nadvornik · 2024-04-16T13:40:01Z

command.go

+}
+
+// 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 {


It could be useful to have some option to add multiple flags in one call (like in AddFlagHelpGroup)

I second this point, having a variadic function would be welcomed!
The implementation could be something like this:

func (c *Command) AddFlagsToHelpGroupID(groupID string, flags ...string) error { for _, flag := range flags { err := AddFlagToHelpGroupID(flag, groupID) if err != nil { return err } } return nil }

nadvornik · 2024-04-17T12:57:06Z

command.go

+Flags:
+{{$cmd.UsageByFlagHelpGroupID "" | trimTrailingWhitespaces}}{{end}}
+
+{{.Title}} Flags:


This can cause problems if localization support is added.
{{.Title}}: is probably better.

jzelinskie · 2024-05-10T15:43:13Z

I noticed an edge case for a library I wrote to implement this in the past, which is that you probably want to hide a group's usage if all of the flags are hidden.

I'm not sure if you've accounted for this scenario.

nirs · 2024-05-25T00:17:40Z

command.go

-{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{else}}{{$flags := .LocalFlags}}{{range $helpGroup := .FlagHelpGroups}}{{if not (eq (len ($cmd.UsageByFlagHelpGroupID "")) 0)}}
+
+Flags:


"Flags" and "Title Flags" are not consistent. It would be nice if all flags are grouped, and so every group has a meaning full name.

If only some flags are grouped, maybe the rest (the un-grouped flags) can appear last instead of first?

We can have 2 reasons to group flags:

Move down related flags that are not common to the end

Move up important flags that are very common to make them easier to find

Example:

Common flags: --foo int ... --bar string ... Security flags: --insecure disable TLS certificate verification --ca-file path to ca certificate Global flags: ...

We probably could use example from real commands to evaluate this.

nirs · 2024-05-25T00:35:53Z

command_test.go

+		b := "b"
+		s := "s"
+		i := "i"
+		g := "g"


These variable do not help much. Maybe using more meaningful names could be better.

nirs · 2024-05-25T00:37:36Z

command_test.go

+
+	t.Run("add flag to flag help group", func(t *testing.T) {
+		child := &Command{Use: "child", Run: emptyRun}
+		rootCmd := &Command{Use: "root", Run: emptyRun}


child and rootCmd are not consistent. I think changing rootCmd to root will help.

nirs · 2024-05-25T00:40:33Z

command_test.go

+		child.AddFlagHelpGroup(&group)
+
+		_ = child.AddFlagToHelpGroupID(b, group.ID)
+		_ = child.AddFlagToHelpGroupID(s, group.ID)


This add the flag to the help group - not the to help group id. Rename to AddFlagToHelpGroup?

nirs · 2024-05-25T00:52:53Z

command.go

+			if groupID == "" {
+				fs.AddFlag(f)
+			}


Maybe add a constant for the special empty group id?

const NoGroup = ""

nirs · 2024-05-25T00:54:08Z

command.go

+// 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" {


A constant for "global" would be nice.

nirs · 2024-05-25T00:58:49Z

command.go

+}
+
+// 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"


Seems that the code return help for single flag group, not help split by groups. Function comment needs update?

Also maybe rename the function to UsageForHelpGroup()?

feat: add flag help groups

e9498ae

Issue spf13#1327

pedromotita mentioned this pull request Mar 7, 2024

Add group flags #1778

Draft

paulopacitti reviewed Mar 7, 2024

View reviewed changes

paulopacitti approved these changes Mar 9, 2024

View reviewed changes

eiffel-fl approved these changes Mar 12, 2024

View reviewed changes

wallrj mentioned this pull request Apr 9, 2024

WIP: Benchmark tool cert-manager/cmctl#46

Closed

nadvornik reviewed Apr 16, 2024

View reviewed changes

nadvornik reviewed Apr 17, 2024

View reviewed changes

nadvornik mentioned this pull request Apr 19, 2024

Add flag groups in help text uyuni-project/uyuni-tools#255

Merged

2 tasks

jpmcb self-requested a review April 19, 2024 13:34

jpmcb added area/cobra-command Core `cobra.Command` implementations size/XL Denotes a PR that exceeds 200 lines. Caution! go Pull requests that update Go code labels Apr 19, 2024

nirs reviewed May 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add flag help groups #2117

feat: add flag help groups #2117

pedromotita commented Mar 7, 2024 •

edited

Loading

CLAassistant commented Mar 7, 2024 •

edited

Loading

paulopacitti left a comment

paulopacitti Mar 7, 2024

pedromotita Mar 8, 2024

paulopacitti Mar 9, 2024

eiffel-fl left a comment •

edited

Loading

eiffel-fl Mar 12, 2024 •

edited

Loading

pedromotita Mar 15, 2024 •

edited

Loading

eiffel-fl Mar 15, 2024

nirs May 25, 2024

eiffel-fl Mar 12, 2024

pedromotita Mar 15, 2024

eiffel-fl Mar 15, 2024

eiffel-fl Mar 12, 2024

pedromotita Mar 15, 2024

eiffel-fl Mar 15, 2024

nadvornik Apr 16, 2024

eiffel-fl Apr 18, 2024

nadvornik Apr 17, 2024

jzelinskie commented May 10, 2024 •

edited

Loading

nirs May 25, 2024

nirs May 25, 2024

nirs May 25, 2024

nirs May 25, 2024

nirs May 25, 2024

nirs May 25, 2024

nirs May 25, 2024

feat: add flag help groups #2117

Are you sure you want to change the base?

feat: add flag help groups #2117

Conversation

pedromotita commented Mar 7, 2024 • edited Loading

Description

Related Issues

Implementation Details

CLAassistant commented Mar 7, 2024 • edited Loading

paulopacitti left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eiffel-fl left a comment • edited Loading

Choose a reason for hiding this comment

eiffel-fl Mar 12, 2024 • edited Loading

Choose a reason for hiding this comment

pedromotita Mar 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jzelinskie commented May 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pedromotita commented Mar 7, 2024 •

edited

Loading

CLAassistant commented Mar 7, 2024 •

edited

Loading

eiffel-fl left a comment •

edited

Loading

eiffel-fl Mar 12, 2024 •

edited

Loading

pedromotita Mar 15, 2024 •

edited

Loading

jzelinskie commented May 10, 2024 •

edited

Loading