search

commander-rb / commander

The complete solution for Ruby command-line executables
MIT License
823 stars 74 forks source link

Revise help output with default command #44

Closed nafu closed 6 years ago

nafu commented 7 years ago

@ggilder Thank you for maintaining great gem. 😄

Description

Add details information about default_command to help output. You can see sample outputs with rspec.

Commander::HelpFormatter::TerminalCompact

global help https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L12 ``` test something Commands: help Display global or [command] help documentation install gem Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```
global help with default_command https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L42 ``` test something Commands: (* default) help Display global or [command] help documentation install gem * Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs Options for install gem: --testing-command Testing command --testing-command-second Testing command second ```
global help with default_command that has not command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L81 ``` test something Commands: (* default) help Display global or [command] help documentation install gem * Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```

Commander::HelpFormatter::Terminal

global help https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L12 ``` NAME: test DESCRIPTION: something COMMANDS: help Display global or [command] help documentation install gem Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```
global help with default_command that has command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L41 ``` NAME: test DESCRIPTION: something COMMANDS: (* default) help Display global or [command] help documentation install gem * Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs OPTIONS for install gem: --testing-command Testing command --testing-command-second Testing command second ```
global help with default_command that has not command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L79 ``` NAME: test DESCRIPTION: something COMMANDS: (* default) help Display global or [command] help documentation install gem * Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```

Motivation and Context

Even if you set default_command, the help command does not show the information about default_command. It is very helpful that you can see the default_command and its options with help command. 🚀

I updated not only erb files but rspec so that you can make sure this behavior.

mfurtak commented 7 years ago

This is really important for fastlane's use of Commander :+1:

hjanuschka commented 7 years ago

@nafu really great - thx for this PR

KrauseFx commented 7 years ago

Thanks for the review, so glad to see a super fast response time here @ggilder 👍 Thanks for your help

nafu commented 7 years ago

@ggilder I addressed the feedback, and left the comment about mark for default_command. Thanks for your help.

Commander::HelpFormatter::TerminalCompact

global help https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L12 ``` test something Commands: help Display global or [command] help documentation install gem Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```
global help with default_command https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L42 ``` test something Commands: (* default) help Display global or [command] help documentation install gem * Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs Options for install gem: --testing-command Testing command --testing-command-second Testing command second ```
global help with default_command that has not command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_compact_spec.rb#L81 ``` test something Commands: (* default) help Display global or [command] help documentation install gem * Install some gem test test description Global Options: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```

Commander::HelpFormatter::Terminal

global help https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L12 ``` NAME: test DESCRIPTION: something COMMANDS: help Display global or [command] help documentation install gem Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```
global help with default_command that has command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L41 ``` NAME: test DESCRIPTION: something COMMANDS: (* default) help Display global or [command] help documentation install gem * Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs OPTIONS for install gem: --testing-command Testing command --testing-command-second Testing command second ```
global help with default_command that has not command option https://github.com/nafu/commander/blob/06283baedce0db38d40e7dc28af8561751648ab6/spec/help_formatters/terminal_spec.rb#L79 ``` NAME: test DESCRIPTION: something COMMANDS: (* default) help Display global or [command] help documentation install gem * Install some gem test test description GLOBAL OPTIONS: -h, --help Display help documentation -v, --version Display version information -t, --trace Display backtrace when an error occurs ```
nafu commented 7 years ago

@ggilder I also added another specs to make sure default_command behavior, could you review again? Thanks!

KrauseFx commented 7 years ago

Hey @ggilder, let us know if there is anything else you need from our side. Once that change is merged, we'd love a new release for this, so we can start using it across all of @fastlane. No worries if it takes longer, just let us know so that we can use a fork in the mean-time 👍

ggilder commented 7 years ago

Hi, sorry for the delay reviewing, been busy with the day job :)

I think the major snag for me is around the formatting. The asterisk feels kind of clunky, and I'm wondering if just adding another section would make more sense. Example:

  NAME:

    test

  DESCRIPTION:

    something

  COMMANDS:

    help          Display global or [command] help documentation
    install gem   Install some gem
    test          test description

  DEFAULT COMMAND:

    install gem

  GLOBAL OPTIONS:
....

Honestly it's hard because a "default command" is kind of a weird concept. Most of the oft-cited examples of "monolith" CLIs like git don't have them, so there's not much prior art as far as how a default command would be indicated in help text. Please direct me to examples if you know of any, I'm curious to see how this handled elsewhere!

ggilder commented 6 years ago

Closing since this has not been updated in a while. Please feel free to reopen if this is still an issue for you.

KrauseFx commented 6 years ago

Thanks, we're using a fork for fastlane, and everything's working great there 👍

ggilder commented 6 years ago

Ok. You may want to rebase on top of the changes from 4.4.4 which I just released.

nafu commented 6 years ago

Thanks :+1: