imp: Add exitcode::USAGE exit code as suggested in #1327

[danielthegray]

The reason to do this is described well in issue #1327.
It is also a recommendation of the Rust book itself:
https://rust-cli.github.io/book/in-depth/exit-code.html

I have run the tests with no failures:

$ cargo test --no-default-features
...
test result: ok. 286 passed; 0 failed; 11 ignored; 0 measured; 0 filtered out
$ cargo test --features "yaml unstable"
...
test result: ok. 286 passed; 0 failed; 14 ignored; 0 measured; 0 filtered out

[danielthegray]

Thank you for merging it! I think there are some spots where the documentation needs to be updated as well.

EDIT: I've looked and can't seem to find the place I saw earlier. Anyway, thanks a lot!

[BurntSushi]

Could the addition of a new dependency here be reconsidered? This is adding a non-optional crate dependency just to use a single number. These numbers are pretty static, so it'd be just fine to define const USAGE: ExitCode = 64; internally IMO.

Moreover, exitcode itself really isn't giving you much here. Arguably, if exit codes differed by platform, then exitcode could be doing the laborious work of picking the correct exit code for you given the use case and platform. But it doesn't do that. Internally, there are no platform specific definitions. On Windows, it seems that there are no strong conventions to follow.

On Unix, it seems like many applications don't bother with this at all. On my Linux system with GNU ls:

$ ls --not-an-option
ls: unrecognized option '--not-an-option'
Try 'ls --help' for more information.
$ echo $?
2

On macOS:

$ ls --not-an-option
ls: illegal option -- -
usage: ls [-@ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1%] [file ...]
$ echo $?
1

Indeed, it's not actually clear to me that sysexits.h is actually standard. In most cases I'm aware of, a CLI usage error results in an exit code of 2, not 64.

So I guess I've muddled two concerns here:

1. Adding a new non-optional dependency that IMO does not carry its weight. This adds a totally new project that dependents of clap now also need to audit.
2. It is not clear to me that the behavior here is actually ideal. I'd rather that clap conform to established custom rather than well meaning attempts to make exit codes more meaningful.

[Dylan-DPC-zz]

I agree with @BurntSushi here. Clap is already a big project that adding a new dependency should be only in required justifiable cases

[pksunkara]

Yup, my bad. I thought the exit codes differed on windows.