command line's 'help' could be more helpful

[mr-fixit]

If I type an unrecognized command, such as $ swiftlint --help, or $ swiftlint --version, I'm told

Unrecognized command: '--help'. See `swiftlint help`.

When I ask $ swiftlint help, I'm told what the commands are, including the command for getting the current version. But I am not told the current version. I have to type that command.

I propose that

1. the output triggered by an unrecognized command include the "help" text itself.

2. -help and --help both be recognized as valid
   2.1) -v and --version both be valid, and produce the same output as the currently supported $ swiftlint version

3. the help output include the version string, e.g.

   swiftlint version 0.13.2

   Available commands:
   autocorrect Automatically correct warnings and errors
   help Display general or command-specific help
   lint Print lint warnings and errors (default command)
   rules Display the list of rules and their identifiers
   version Display the current version of SwiftLint

[marcelofabri]

Just as a comparison, I've run --help for some popular tools (gcd, git, xcodebuild, pod and fastlane) and none of them include the version on its help text.

I'm not so sure I'd like to see the help if I type an unrecognized command as I could just had a typo and the help information would "pollute" the terminal.

I agree with recognizing -h and --help.

[ZevEisenberg]

-v and --version would also be very much appreciated, IMHO.

[marcelofabri]

Also there's already #531 to track supporting -h and --help

[jpsim]

Agreed, and this has annoyed me since day one, especially the non-Unixy approach to CLI argument syntax of Commandant, which is the library we use to handle this.

Fixing this upstream in Commandant would be ideal, but moving entirely away from the verb-based syntax would be unfortunate since it would break so much existing usage.

[mr-fixit]

Does #531 suggest that I can type -h or --help at the end of any invocation of the command, even those with unrecognized parameters such as

$ swiftlint foo --foo --help

and get the same results as if I'd typed $ swiftlint --help? If so, I didn't realize that was a thing.

[marcelofabri]

I don't think that was mentioned there, but I think #531 is similar to your second point (not the first).

[mr-fixit]

@marcelofabri, I agree with you, #531 is a more detailed description of what I might have meant by 'recognized as valid'

[axello]

Not only that, but in the absence of a proper man page, it would also be helpful if the 'help' command would display ALL possible arguments as well.
e.g. --path. This is not mentioned anywhere on the main github page, nor in the help
or --config. Very helpful, but not mentioned.

Better overdo it, like nmap, than hold back information, is my motto.

[BradPatras]

Thank you @axello, I was looking all over trying to find out how to include the config path when using the command line interface. And ironically the only place I found that mentions it is your comment on this dead issue about how bad documentation is...

[stale]

This issue has been automatically marked as stale because it has not had any recent activity. Please comment to prevent this issue from being closed. Thank you for your contributions!

[ZevEisenberg]

Does SwiftLint already use Swift Argument Parser? If not, moving to it would probably satisfy much of this "for free."

[jpsim]

No we use Commandant (same as Carthage), but I’ve been considering switching over to Swift Argument Parser.

Other than the work involved to migrate, we should also assess the impact to existing users, if it’s possible to keep the current command syntax working, etc.

[jpsim]

We've migrated to swift-argument-parser, which handles this better than Commandant did.

$ # Before
$ swiftlint --help
Unrecognized arguments: --help
$ # After
$ swiftlint --help
OVERVIEW: A tool to enforce Swift style and conventions.

USAGE: swiftlint <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  analyze                 Run analysis rules
  docs                    Open SwiftLint documentation website in the default web browser
  generate-docs           Generates markdown documentation for all rules
  lint (default)          Print lint warnings and errors
  rules                   Display the list of rules and their identifiers
  version                 Display the current version of SwiftLint

  See 'swiftlint help <subcommand>' for detailed help.

I'd appreciate if you could try out SwiftLint on the master branch and share if anything's improved or regressed for you.

[mr-fixit]

Thanks, I tried this out in 0.42. Vast improvement. I noticed a few wrinkles, but no regressions:

One

I'm not sure what I expected $ swiftlint help version --help to produce, but the following wasn't it:

OVERVIEW: Show subcommand help information.

USAGE: swiftlint help [<subcommands> ...]

ARGUMENTS:
  <subcommands>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

Two

@axello 's suggestion here wasn't incorporated. --path and --config still aren't mentioned.

Three

The output of any $ swiftlint <anything> [ -h | --help ] doesn't include the version number. I still think that's a nice idea, so I'm just putting out there.

[jpsim]

Thanks for trying it out and for your feedback! For your first point, help <command> --help is a bit unconventional, but I have an idea of how this could be fixed in swift-argument-parser (a hidden --help flag on the help subcommand).

For your second point, yes the help output includes --path and --config. For example, if you run swiftlint lint --help or swiftlint help lint, you get this output:

OVERVIEW: Print lint warnings and errors

USAGE: swiftlint lint <options>

ARGUMENTS:
  <paths>                 List of paths to the files or directories to lint. 

OPTIONS:
  --config <config>       The path to one or more SwiftLint configuration files, evaluated as a parent-child hierarchy. 
  --fix, --autocorrect    Correct violations whenever possible. 
  --use-alternative-excluding
                          Use an alternative algorithm to exclude paths for `excluded`, which may be faster in some cases. 
  --use-script-input-files
                          Read SCRIPT_INPUT_FILE* environment variables as files. 
  --strict                Upgrades warnings to serious violations (errors). 
  --lenient               Downgrades serious violations to warnings, warning threshold is disabled. 
  --force-exclude         Exclude files in config `excluded` even if their paths are explicitly specified. 
  --benchmark             Save benchmarks to `benchmark_files.txt` and `benchmark_rules.txt`. 
  --reporter <reporter>   The reporter used to log errors and warnings. 
  --path <path>           The path to the file or directory to lint. 
  --use-stdin             Lint standard input. 
  --quiet                 Don't print status logs like 'Linting <file>' & 'Done linting'. 
  --cache-path <cache-path>
                          The directory of the cache used when linting. 
  --no-cache              Ignore cache when linting. 
  --enable-all-rules      Run all rules, even opt-in and disabled ones, ignoring `only_rules`. 
  --version               Show the version.
  -h, --help              Show help information.

So --path and --config are definitely there.

However, if you run swiftlint --help you get the help for all the SwiftLint subcommands rather than the help for the default subcommand, but that's as it should be IMHO:

$ swiftlint --help
OVERVIEW: A tool to enforce Swift style and conventions.

USAGE: swiftlint <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  analyze                 Run analysis rules
  docs                    Open SwiftLint documentation website in the default web browser
  generate-docs           Generates markdown documentation for all rules
  lint (default)          Print lint warnings and errors
  rules                   Display the list of rules and their identifiers
  version                 Display the current version of SwiftLint

  See 'swiftlint help <subcommand>' for detailed help.

Finally your third point, swiftlint --version and swiftlint version both output the version number. I do think including it in the top-level help output is a good idea, along with the OVERVIEW and USAGE entries that are already included there.

Thanks again for your feedback.

[mr-fixit]

Thank YOU (et. al) for your contributions to an awesome tool.

[jpsim]

I filed a PR with your suggestion to include the version number in the help output: apple/swift-argument-parser#258