Make it easy to show subcommands before options

[xixixao]

We have a main command that only takes --version and --help, but has a bunch of subcommands. In the main help printout we want to show the subcommands first, because those matter. For example of others programs doing something like this see Vercel's CLI.

It doesn't seem to be possible currently to reorder these sections without large reimplementation of help?

Would you be open to a PR?

[shadowspawn]

In fact, that may have been the previous order! #500 #529 #652

I found one other order related issue: #1234

[shadowspawn]

It doesn't seem to be possible currently to reorder these sections without large reimplementation of help?

Currently, this could be achieved by overriding formatHelp in the Help class and changing the order of the sections. Yes, this is a chunk of code to copy-paste.

[shadowspawn]

Would you be open to a PR?

Certainly willing to discuss or look! No promise to land something. Did you have some approach in particular in mind?

(The current help setup was added in #1365. Part of the intent was to make customisation easier, but of course only some things are actually easy as a result.)

[xixixao]

Thanks for checking @shadowspawn ! Roughly the idea would be to pull out each of the currently // commented blocks from formatHelp into a method. The built-in formatHelp would then look like:

[].concat(
  helpUsage(),
  helpCommandDescription(),
  helpArguments(),
  helpOptions(),
  helpGlobalOptions(),
  helpCommands(),
).join('\n')

The methods can return strings or lines (lines might allow more customization but might "expose" the implementation more than you'd like?).

To satisfy my original PR request, I could then implement formatHelp using these methods, like:

[].concat(
  helpUsage(),
  helpCommands(),
  helpOptions(),
).join('\n')

[shadowspawn]

My feeling is it is going to refactor the code into quite small pieces without adding a lot of flexibility, or solving issues that have been reported in past.

I am happy to leave this issue open to see if it attracts support, or if other issues come up which overlap with the idea.

You could try some code for a proof of concept PR if you are keen. (But if it doesn't change my mind in short-term then I'll close the PR and keep the issue open.)

[shadowspawn]

I was having a look at some other utilities with lots of commands, and none of git or hg or npm display information about their global options by default in their command-line help.

So a different approach for your case might be to just suppress the options in the top level help. Not saying it is a great solution, but it is simpler to achieve than reordering!

import { Command } from 'commander';

const program = new Command('my-command');

program.command('add').description('helpful informative text goes here');
program.command('subtract').description('helpful informative text goes here');
program.command('multiple').description('helpful informative text goes here');
program.command('divide').description('helpful informative text goes here');
program.command('server').description('helpful informative text goes here');

// Hide options at top level. Do this after adding subcommands so they are not affected.
program.configureHelp({
  visibleOptions: () => { return []; }
});
program.parse();

$ node index.mjs    
Usage: my-command [options] [command]

Commands:
  add             helpful informative text goes here
  subtract        helpful informative text goes here
  multiple        helpful informative text goes here
  divide          helpful informative text goes here
  server          helpful informative text goes here
  help [command]  display help for command

[xixixao]

So a different approach for your case might be to just suppress the options in the top level help.

I forgot to mention this but this is indeed what we've done.

[shadowspawn]

Overlapping ideas, there is some user implemented support for "moving" options and constructing "sections" before formatting in: #1897 (comment) (see "sections" in the formatHelp section)

[shadowspawn]

Oclif allows ordering changes via "sections" and customising the help: oclif/oclif#181 (comment)

Also of interest, the issue is about support for environment variables in the help, which has also been requested for Commander.

[shadowspawn]

I opened a proof of concept of adding "sections" and allowing section reordering: #2196

[shadowspawn]

There has only been one like for this issue. I think the work to make this possible will not happen just to simplify reorder, but may fit in with some other refactor in future.

Feel free to open a new issue if it comes up again, with new information and renewed interest.

Thank you for your contributions.