Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make it easy to show subcommands before options #1870

Closed
xixixao opened this issue Apr 25, 2023 · 11 comments
Closed

Make it easy to show subcommands before options #1870

xixixao opened this issue Apr 25, 2023 · 11 comments

Comments

@xixixao
Copy link

xixixao commented Apr 25, 2023

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
Copy link
Collaborator

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

I found one other order related issue: #1234

@shadowspawn
Copy link
Collaborator

shadowspawn commented Apr 26, 2023

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
Copy link
Collaborator

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
Copy link
Author

xixixao commented Apr 27, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Author

xixixao commented May 2, 2023

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
Copy link
Collaborator

shadowspawn commented Jun 28, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator

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

@shadowspawn
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants