Is it possible to group subcommands in help outout?

[jacobk]

Is it possible to group subcommands similar to https://ajalt.github.io/clikt/documenting/#grouping-options-in-help

I'm building a command with a large number of subcommands and it would be great to group/categorize them in the help output.

Similar to the output of running git without options (example taken from: https://clig.dev/#help)

usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone     Clone a repository into a new directory
   init      Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add       Add file contents to the index
   mv        Move or rename a file, a directory, or a symlink
   restore   Restore working tree files
   rm        Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect    Use binary search to find the commit that introduced a bug
   diff      Show changes between commits, commit and working tree, etc
   grep      Print lines matching a pattern
   log       Show commit logs
   show      Show various types of objects
   status    Show the working tree status

[ajalt]

So one option is to write the grouped commands in the root command help manually, which is what git does. But if you want to automate it, it's not too hard to customize the help formatter to group subcommands by using e.g. a help tag to specify the group:

class MyHelpFormatter(context: Context) : MordantHelpFormatter(context) {
    override fun shouldShowTag(tag: String, value: String): Boolean {
        return super.shouldShowTag(tag, value) && tag != "group"
    }

    override fun renderCommands(parameters: List<ParameterHelp>): List<RenderedSection> {
        val grouped = parameters.filterIsInstance<ParameterHelp.Subcommand>()
            .groupBy { it.tags["group"] }
        return grouped.mapNotNull { (group, commands) ->
            super.renderCommands(commands).firstOrNull()?.let {
                if (group == null) it else it.copy(title = Text(styleSectionTitle(group)))
            }
        }
    }
}


fun main(args: Array<String>) {
    val root = NoOpCliktCommand(name = "git", help="These are common Git commands used in various situations:").context { helpFormatter = { MyHelpFormatter(it) } }
    val g1 = mapOf("group" to "start a working area (see also: git help tutorial)")
    val g2 = mapOf("group" to "work on the current change (see also: git help everyday)")
    val g3 = mapOf("group" to "examine the history and state (see also: git help revisions)")
    root.subcommands(
        NoOpCliktCommand(name="clone", help = "Clone a repository into a new directory", helpTags = g1),
        NoOpCliktCommand(name="init", help = "Create an empty Git repository or reinitialize an existing one", helpTags = g1),
        NoOpCliktCommand(name="add", help = "Add file contents to the index", helpTags = g2),
        NoOpCliktCommand(name="mv", help = "Move or rename a file, a directory, or a symlink", helpTags = g2),
        NoOpCliktCommand(name="restore", help = "Restore working tree files", helpTags = g2),
        NoOpCliktCommand(name="rm", help = "Remove files from the working tree and from the index", helpTags = g2),
        NoOpCliktCommand(name="bisect", help = "Use binary search to find the commit that introduced a bug", helpTags = g3),
        NoOpCliktCommand(name="diff", help = "Show changes between commits, commit and working tree, etc", helpTags = g3),
        NoOpCliktCommand(name="grep", help = "Print lines matching a pattern", helpTags = g3),
        NoOpCliktCommand(name="log", help = "Show commit logs", helpTags = g3),
        NoOpCliktCommand(name="show", help = "Show various types of objects", helpTags = g3),
        NoOpCliktCommand(name="status", help = "Show the working tree status", helpTags = g3),
    )
    root.main(args)
}

[jacobk]

Nice! I will try that. Thanks for such a detailed reply.