Add ability to group commands in help message

[itskingori]

Wondering if:

1. Is this possible via custom help commands? i.e. cmd.SetHelpCommand(cmd *Command)
2. Is this something you (the author) would consider? Or you (the reader) who might have come across this by searching through the issues?

We don't have to group all commands. Maybe just the root command. A good example

$ kubectl help
kubectl controls the Kubernetes cluster manager.

Find more information at: https://kubernetes.io/docs/reference/kubectl/overview/

Basic Commands (Beginner):
  create         Create a resource from a file or from stdin.
  expose         Take a replication controller, service, deployment or pod and expose it as a new Kubernetes Service
  run            Run a particular image on the cluster
  set            Set specific features on objects

Basic Commands (Intermediate):
  explain        Documentation of resources
  get            Display one or many resources
  edit           Edit a resource on the server
  delete         Delete resources by filenames, stdin, resources and names, or by resources and label selector

Deploy Commands:
  rollout        Manage the rollout of a resource
  scale          Set a new size for a Deployment, ReplicaSet, Replication Controller, or Job
  autoscale      Auto-scale a Deployment, ReplicaSet, or ReplicationController

Cluster Management Commands:
  certificate    Modify certificate resources.
  cluster-info   Display cluster info
  top            Display Resource (CPU/Memory/Storage) usage.
  cordon         Mark node as unschedulable
  uncordon       Mark node as schedulable
  drain          Drain node in preparation for maintenance
  taint          Update the taints on one or more nodes

Troubleshooting and Debugging Commands:
  describe       Show details of a specific resource or group of resources
  logs           Print the logs for a container in a pod
  attach         Attach to a running container
  exec           Execute a command in a container
  port-forward   Forward one or more local ports to a pod
  proxy          Run a proxy to the Kubernetes API server
  cp             Copy files and directories to and from containers.
  auth           Inspect authorization

Advanced Commands:
  diff           Diff live version against would-be applied version
  apply          Apply a configuration to a resource by filename or stdin
  patch          Update field(s) of a resource using strategic merge patch
  replace        Replace a resource by filename or stdin
  wait           Experimental: Wait for a specific condition on one or many resources.
  convert        Convert config files between different API versions

Settings Commands:
  label          Update the labels on a resource
  annotate       Update the annotations on a resource
  completion     Output shell completion code for the specified shell (bash or zsh)

Other Commands:
  api-resources  Print the supported API resources on the server
  api-versions   Print the supported API versions on the server, in the form of "group/version"
  config         Modify kubeconfig files
  plugin         Provides utilities for interacting with plugins.
  version        Print the client and server version information

Usage:
  kubectl [flags] [options]

Use "kubectl <command> --help" for more information about a given command.
Use "kubectl options" for a list of global command-line options (applies to all commands).

[pbarker]

also interested if this is possible

[NoGroceries]

also interested

[medyagh]

+1

[itskingori]

Just came across https://github.com/google/kf/issues/55 and there's a link to a comment explaining how it can be done, see https://github.com/google/kf/issues/55#issuecomment-493706608. I haven't tried it yet. That said, google/kf#130 is an example PR of how that approach could be used

[jharshman]

I think this is a great addition and has obvious use cases. I will target to get this in a future release after 1.0.0.

[ghostsquad]

related to #682

[github-actions]

This issue is being marked as stale due to a long period of inactivity

[ghostsquad]

Not stale

[hitzhangjie]

Before I wrote a golang debugger, I need this feature, too. Though it's not as convenient as we expected, but indeed cobra provides the basic support for this.

As we all know, a debugger may support breakpoints, list source, print variables and types, so I think it's better to group the commands by category of functions.

You can reference the code here, https://sourcegraph.com/github.com/hitzhangjie/godbg@915799c5979b00699729d318ec1226cd75e9f372/-/blob/cmd/debug/shell.go#L143

To summarize the code:

• annotate your subcommand by cobra.Command.Annotation field
• custozmize a help message function for rootCmd
• in your customized help message function, group the subcommands by the annotation

To write several lines of code is enough, and you can check the following picture to see whether this manner meet your needs:

[ghostsquad]

pre-emptive not-stale