Show usage of subcommand in global help

[pitkley]

I don't know if this feature exists, if so, I have not found it yet. What I'm looking for is a way to see the usage of a subcommand in the help shown by the help subcommand or the global --help flag. Compare the actual behavior to the expected behavior for an example.

---

Rust Version

rustc 1.17.0 (56124baa9 2017-04-24)

Affected Version of clap

2.24.1

Actual Behavior Summary

$ ./test --help
test 

USAGE:
    test [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help          Prints this message or the help of the given subcommand(s)
    subcommand    subcommand help

The SUBCOMMANDS: section only shows the subcommands that exist, not what parameters they require.

One has to ask for the specific help:

$ ./test subcommand --help
test-subcommand 

USAGE:
    test subcommand <PARAM>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <test>

Expected Behavior Summary

$ ./test --help
test 

USAGE:
    test [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help
                  Prints this message or the help of the given subcommand(s)
    subcommand <PARAM>
                  subcommand help

Instead of having to look at every individual help output, the SUBCOMMANDS: section shows the USAGE: section of the subcommands.

Sample Code

extern crate clap;
use clap::{Arg, App, SubCommand};

fn main() {
    let matches = App::new("test")
        .subcommand(SubCommand::with_name("subcommand")
                        .about("subcommand help")
                        .arg(Arg::with_name("PARAM").required(true)))
        .get_matches();
}

Debug output

I can supply this at a later time if required.

[kbknapp]

Thanks for the suggestion and all the details! 👍

This feature doesn't exist (yet) could be added as an AppSettings variant, although my only concern is recursively following that chain with multiple nested subcommands.

Since I'm actively working on 3x I think this is something I'll try to add then, because the code clean ups I've done so far would make this far easier to implement, and/or people to contribute to. However, if someone wants this done immediately I'd be willing to assist in mentoring or answering questions on how this could be done.

[pitkley]

Thanks for the reply.

1. Regarding your concerns on recursion: I personally think that the first usage level "down" would be enough, I wouldn't even be sure how to print another level without the output getting crowded or illegible.

   I.e. for this code:

   extern crate clap;
   use clap::{Arg, App, SubCommand};
   
   fn main() {
       let matches = App::new("test")
           .subcommand(SubCommand::with_name("subcommand")
                           .about("subcommand help")
                           .arg(Arg::with_name("PARAM").required(true))
                           .subcommand(SubCommand::with_name("nested")
                                           .arg(Arg::with_name("NESTED").required(true)))
           .get_matches();
   }

   I would simply expect the usage on subcommand to gain [SUBCOMMAND]:

   $ ./test --help
   test 
   
   USAGE:
       test [SUBCOMMAND]
   
   FLAGS:
       -h, --help       Prints help information
       -V, --version    Prints version information
   
   SUBCOMMANDS:
       help
                     Prints this message or the help of the given subcommand(s)
       subcommand <PARAM> [SUBCOMMAND]
                     subcommand help

   But if you could think of a way to cleanly print even those subcommands, it might be worth while implementing too.

2. Regarding an implementation for 2.x: while I would try and take a stab at it, especially since you offered your assistance, I personally can wait for 3.x to either have that feature or help with an implementation once 3.x is ready for contributions.

[kbknapp]

I'm going to close this for the time being, but may re-address it once 3.x is out

[CreepySkeleton]

Leaving it closed for the time being

[buck-ross]

Has there been any update on this? I see the issue has been re-opened, but there doesn't seem to be any follow-up that I can see.

[epage]

No updates. A lot of our focus right now is in other areas like API clean up, shrinking binary size, fixing bugs, etc.

I am curious if the solution proposed in #1334 might be a viable alternative to meet the same needs. If we can find more common solutions to problems, it can help us meet our goal of keeping binary sizes and compile times down,.

[epage]

I lean in favor of #1334 instead and am closing in favor of that as usually someone is either caring about one command at a time or with them flattened and the build-time / binary size cost of supporting both wouldn't be great.

If people make the case for this being needed, I'm ok with re-opening this.