Recommendation: gh --help and gh [command] --help descriptions

[ericnewton76]

Hi. Just trying out gh and realized many of the commands don't have much (if at all) descriptions

$ gh repo --help
usage: gh <command> [payload] [--flags] [--verbose] [--no-hooks]

List of available commands:
  re, repo Provides a set of util commands to work with Repositories.
    -B, --browser* (Boolean)
    -c, --clone* (Boolean)
    -C, --color (String)
    -D, --delete* (String)
    --description (String)
    -d, --detailed (Boolean)
    --gitignore (String)
    -f, --fork* (String)
    --homepage (String)
    --init (Boolean)
    -L, --label (Boolean)
    -l, --list* (Boolean)
    -N, --new* (String)
    -O, --organization (String)
    --page (String)
    --per_page (String)
    -p, --private (Boolean)
    -P, --protocol (String)
    -r, --repo (String)
    -t, --type (all, forks, member, owner, public, private, sources)
    -U, --update* (String)
    -u, --user (String)


(*) Flags that can execute an action.
'gh help' lists available commands.
'gh help -a' lists all available subcommands.

So I'm somewhat unsure how to use it without dipping into the source code.

Like what does --gitignore "string" do?

What command line parser are you using? I'm familiar with https://www.npmjs.com/package/commander

[protoEvangelion]

Hey @ericnewton76 that is a fantastic recommendation.

Also sometimes I would like to see flags for a cmds for a level deeper like at gh repo --list. Most of the time the answer is in the readme: https://github.com/node-gh/gh#examples-19

But I agree that it should be accessible at the cmd line level. This is a CLI tool after all right?!

We are using an option parser which is pretty low level and does not include a help cmd which we wrote from scratch. Additionally, we cannot pass an object for each option to this option parser like { browser: { type: Boolean, description: 'Open in browser' }. Ideally in the future we would use a package that includes this functionality and will provide more "helpful" help messages.

If anyone has any recommendations on how to implement this I am all ears!

[ericnewton76]

Like I mentioned before, I am pretty familiar with npm commander for option parsing, allows for subcommands and (sub-sub commands I think). Commander takes a very different approach than noopt, where you define the valid options (and possibly valid values) and then parse the arguments based on those policies. Noopt goes the other way (not neccesarily bad, but how useful is that?)

Commander defines the options:

program.option('-l,--list', "List Repos for the user")
  .option("--per-page", "Sets number of items per page", -1)
  .option("-t,--type", "(description of type).  Allowed values: all,forks,member,owner,public,private,sources)")

program.parse(process.argv)

//now program object has the options:
if(program.verbose) { turnOnVerbose(); }
if(program.type == "all") { doTypeAll(program["per-page"]); }

Can even have a function for defaultValue, which can do type checking on options. Its pretty powerful, with the goal in mind of establishing what's available on the command line, versus noopt's handling of just taking everything encountered on the commandline and presenting it as a javascript object.

One great thing about commander is when --help is invoked, its an automagic thing, for the most part. Also allows for a help callback to possibly list out values without having to embed them in the above descriptions, (ie, str substitution, like "#{type_options_enumerated}#" and replace that str with the Object.keys of an object that is the actual options, etc.

On another note, I feel like --list shouldn't be an option, but a subcommand of repo... so any of those "flags that can execute an action" change to a subcommand, like so:

gh repo list -u user --verbose

Although I'm not sure how you guys feel about that aspect (ie, make subsub-commands proper subsub commands... lol)

[protoEvangelion]

Ya I like commander as well and have used it on side projects.

I agree with you that it should be practically considered a sub command ha. It's difficult to reconcile in that I would prefer to stay backwards compatible but also use the sub command signature you mentioned. Even something like gh repo:list -u user would be preferable.

Do you have any thoughts on how to keep this backwards compatible while moving forward with the proper subcommand format?

[ericnewton76]

gh repo:list -u user makes a whole lot more sense to me. (Although not sure about the colon, I believe commander tries to find a subcommand in a separate file, so in this case cmd-repo:list.js but might choke on the ':'.

I would actually just declare the change, kick the version major up, and let the consumers decide when they're ready.

[protoEvangelion]

Thanks for the feedback, this is definitely on my todo list!