Poll: how commands are listed in Help

[shadowspawn]

The list of subcommands in the help uses a format similar to the full "usage", but does not use author supplied custom usage which is arguably a bug. However, a custom usage string could be quite long if it includes all of the available options so I am hesitant to make that the default.

I am wondering about changing the way commands are listed by default and interested in feedback.

For reference in the examples below, the full usage for each command is:

Usage: fab clone [options] <source> [destination]
Usage: fab for-each|forEach [options] <command> [args...]
Usage: fab completion [options]
Usage: fab custom <command> -- [options]

You may vote 👍 for more than one, and may vote 👎 against any you dislike.

[shadowspawn]

1) legacy

This is the existing approach. The [options] is suppressed if there is only --help.

Commands:
  clone [options] <source> [destination]          clone source and install its dependencies
  for-each|forEach [options] <command> [args...]  run specified command on each repo in the forest
  completion                                      (has no options other than --help)
  custom [options] <command>                      command with custom usage string
  help [command]                                  display help for command

[shadowspawn]

2) name only

A name-only listing is often used by utilities with lots of commands like git, npm, docker, and hg.

Commands:
  clone       clone source and install its dependencies
  for-each    run specified command on each repo in the forest
  completion  (has no options other than --help)
  custom      command with custom usage string

  To see the help for a command use 'foo help <command>`.

[shadowspawn]

3. full usage

In particular, this includes any author supplied custom usage strings.

Commands:
  clone [options] <source> [destination]          clone source and install its dependencies
  for-each|forEach [options] <command> [args...]  run specified command on each repo in the forest
  completion [options]                            (has no options other than --help)
  custom <command> -- [options]                   command with custom usage string
  help [command]                                  display help for command

[shadowspawn]

4. name and arguments

   Commands:
   clone <source> [destination]  clone source and install its dependencies
   for-each <command> [args...]  run specified command on each repo in the forest
   completion                    (has no options other than --help)
   custom <command>              command with custom usage string
   help [command]                display help for command