This allows applications to declare, document, and add default values for environment variables that they're sensitive too.

Includes support for the recently-added "advanced" feature to allow documentation of esoteric environment variables without cluttering the help output.

This allows a program to define many subcommands, but have them omitted from the default help view, to keep the high-level subcommands directly visible to the user.

This allows individual subcommands to indicate that they would like to take full control of the 'args' parsing. This is useful for when 'flag' is insufficiently groovy, or when writing wrapper programs where some or even none of the flags need to be interpreted by the wrapper itself (e.g. merely passed through to the target program).

Without this, invocations such as prog subcommand -flag will fail because -flag would be interpreted as an 'unknown flag'.

When running tests in parallel, sometimes race detector (go test -race) fails at the following line. https://github.com/maruel/subcommands/blob/4b22346b79dd1f53c945985bb1243cc141f70aa7/subcommands.go#L334

Example: https://logs.chromium.org/logs/infra/buildbucket/cr-buildbucket.appspot.com/8856422888007344336/+/u/go_test_-race/stdout#L6231_51

Currently, the CommandRun.Run method returns an int. I suspect this is because the original design wanted commands to decide their exit code, but it causes some unfortunate boilerplate: most commands will end up with an error value, and have to manually print it out and decide some code to return, adding a few lines on every return statement.

Some people mitigate some awkwardness by introducing a helper function to call, which translates an error into an int (and prints non-nil errors), but that has other awkwardness in that you have to remember to use that in every return statement in every command's top-level Run method.

Instead of a helper function that you have to call, I recently introduced a wrapper type in my project which allows commands to implement a Run method which returns an error, and then does the error check and translation to integer code in one place. (It also fixes the lack of context.) It works for my project, but ideally this convenience would be pushed into this library too for everyone to share.

I would suggest instead to have the Run method return an error instead of an int; I suspect most commands would be content with exiting with 0 on a nil error, and a 1 on an arbitrary error. For those (few) commands which want to control their exit code, we can introduce an extra type like:

type ExitCode struct {
   Err error
   Code int
}

Directly changing the CommandRun function would be a breaking change, and I'm not sure how amenable people are to that. (With Go modules, it should be slightly easier to avoid breaking people? I think...) But an obvious second choice would be to deprecate the old type and make a new one which returns an error (and, ideally, takes a context too to solve https://github.com/maruel/subcommands/issues/4).

Currently, this package is completely Context-unaware. Context is, however, the sort of thing the top-level main method may want to establish or control from outside the scope of the subcommand (e.g., for signal-based cancellation, factory installation, etc.).

Some solutions, such as https://godoc.org/github.com/luci/luci-go/common/cli, operate by bolting this support onto subcommands. This results in some pretty wonky code, weird inversions, and the creation (or discarding) of multiple Context.

A better solution would be to have subcommands.Run accept a Context and forward it to its CommandRun.

Proposal:

Add DefaultApplication.AllowArgsInFIle or something like that (name suggestions are welcome). If true

• extra text is printed in usage that subcommand and its arguments can be passed through a file
• if first argument starts with @, treat the rest of the argument as a path to the file that contains command line arguments. There must be no other arguments besides @file.

This is needed on Windows where the command line length limit is low.

@maruel @vadimsht