Exclude supercommands from help

[miggs597]

Currently when asking for help with a subcommand we will receive help for it, and all supercommands that precede it. I propose the ability to only print help for the subcommand. The best example of this is in SwiftPM.

Current Behavior:

$ swift package init --help
OVERVIEW: Initialize a new package

USAGE: swift package init <options>

OPTIONS:
  -Xcc <Xcc>              Pass flag through to all C compiler invocations 
  -Xswiftc <Xswiftc>      Pass flag through to all Swift compiler invocations 
  -Xlinker <Xlinker>      Pass flag through to all linker invocations 
  -Xcxx <Xcxx>            Pass flag through to all C++ compiler invocations 
  -c, --configuration <configuration>
                          Build with configuration (default: debug)
  --build-path <build-path>
                          Specify build/cache directory 
  --cache-path <cache-path>
                          Specify the shared cache directory 
  --enable-repository-cache/--disable-repository-cache
                          Use a shared cache when fetching repositories (default: true)
  -C, --chdir <chdir>
  --package-path <package-path>
                          Change working directory before any other operation 
  --multiroot-data-file <multiroot-data-file>
  --enable-prefetching/--disable-prefetching
                          (default: true)
  -v, --verbose           Increase verbosity of informational output 
  --disable-sandbox       Disable using the sandbox when executing subprocesses 
  --manifest-cache <manifest-cache>
                          Caching mode of Package.swift manifests (shared: shared cache, local: package's build directory, none:
                          disabled (default: shared)
  --destination <destination>
  --triple <triple>
  --sdk <sdk>
  --toolchain <toolchain>
  --static-swift-stdlib/--no-static-swift-stdlib
                          Link Swift stdlib statically (default: false)
  --skip-update           Skip updating dependencies from their remote during a resolution 
  --sanitize <sanitize>   Turn on runtime checks for erroneous behavior, possible values: address, thread, undefined, scudo 
  --enable-code-coverage/--disable-code-coverage
                          Enable code coverage (default: false)
  --force-resolved-versions, --disable-automatic-resolution
                          Disable automatic resolution if Package.resolved file is out-of-date 
  --enable-index-store/--disable-index-store
                          Enable or disable  indexing-while-building feature 
  --enable-parseable-module-interfaces
  --trace-resolver
  -j, --jobs <jobs>       The number of jobs to spawn in parallel during the build process 
  --enable-build-manifest-caching/--disable-build-manifest-caching
                          (default: true)
  --emit-swift-module-separately
  --use-integrated-swift-driver
  --experimental-explicit-module-build
  --print-manifest-job-graph
                          Write the command graph for the build manifest as a graphviz file 
  --build-system <build-system>
                          (default: native)
  --netrc
  --netrc-optional
  --netrc-file <netrc-file>
  --type <type>           (default: library)
  --name <name>           Provide custom package name 
  --version               Show the version.
  -help, -h, --help       Show help information.

Proposed Behavior

swift package init --help
OVERVIEW: Initialize a new package

USAGE: swift package init [--type <type>] [--name <name>]

OPTIONS:
  --type <type>           Package type: empty | library | executable | system-module | manifest (default: library)
  --name <name>           Provide custom package name 
  --version               Show the version.
  -help, -h, --help       Show help information.

These changes are fully backwards compatible, with no changes needed to existing sources that depend on ArgumentParser.

To access this new feature a user would just need to add includeSuperCommandInHelp = false to their struct that conforms to ParsableCommand

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[tomerd]

@natecook1000 ptal and let us know so @miggs597 can progress on swiftlang/swift-package-manager#3407

[natecook1000]

@miggs597 Thanks for working on this! After looking further, it doesn't look like this actually needs to be configurable. generateSections really only needs to look at commandStack.last to generate its different help options. The only arguments and options that a command really needs to print are those actually defined in the command either directly or included via @OptionGroup.

You'll still need to use your custom mirror to suppress SwiftToolOptions from being displayed in package init until there's #267 is implemented, but this will help make that possible as well.

[natecook1000]

Let's make this new behavior the default for all commands — you can drop the changes to CommandConfiguration and the documentation update, since it's really a bug that it even has the current behavior.

[natecook1000]

You should be able to just grab the top of the command stack this way...

Suggested change

	var commandsToShowHelp = [ParsableCommand.Type]()
	if let commandType = commandStack.last, !commandType.includeSuperCommandInHelp {
	commandsToShowHelp.append(commandType)
	} else {
	commandsToShowHelp = commandStack
	}
	guard let commandType = commandStack.last else {
	return []
	}

...and then remove the following for-in loop and de-dent its contents.

[natecook1000]

@swift-ci Please test

[tomerd]

@swift-ci Please test

[natecook1000]

🎉

[tomerd]

@natecook1000 we would need a new tag so we can pull this fix into the toolchain build to fix the SwiftPM regression. please let us know when you have one ready!

cc @abertelrud @miggs597 @shahmishal