search

nicklockwood / SwiftFormat

A command-line tool and Xcode Extension for formatting Swift code
MIT License
7.81k stars 632 forks source link

document (and consider changing) exit codes #966

Closed justinmeiners closed 3 years ago

justinmeiners commented 3 years ago

Issue I cannot find any documentation of how the exit codes should behave, can you point me to that information? Can this be added to --help or a man page?

Suggestion

If you are open to suggestion on this topic, I think changing them to match other linting tools would greatly simplify how they are used in CI pipelines, and avoid the need for git-format-staged in precommit hooks.

What I would expect is that if there files are modified by the linter, it should have a non-zero exit code, so that the pre-commit fails, then the programmer has an opportunity to review the changes before committing.

Here is what ESLint, a similar tool for JavaScript does, allowing the functionality I described:

When linting files, ESLint will exit with one of the following exit codes:

0: Linting was successful and there are no linting errors 1: Linting was successful and there is at least one linting error 2: Linting was unsuccessful due to a configuration problem or an internal error.

nicklockwood commented 3 years ago

Thanks for the suggestion - I didn't realize this wasn't documented, but you're right that it should be!

The current codes are:

0: Linting was successful and there are no linting errors 1: Linting was successful and there is at least one linting error 70: Linting was unsuccessful due to a configuration problem, internal error, or malformed input

The use of 70 here is not arbitrary - it's the EX_SOFTWARE error code used in BSD: https://man.openbsd.org/sysexits.3

(although arguably I should be using EX_USAGE, EX_NOINPUT, etc for some of these error states. In any case, you can safely assume that error 1 is a lint failure and anything higher is an error.

justinmeiners commented 3 years ago

Perfect thanks, so just one follow up:

Linting was successful and there are no linting errors

If there was incorrect syntax which got fixed during that run, does that count as a linting error? Or, is 1 only returned if errors remain outstanding in the code, after running the tool.

nicklockwood commented 3 years ago

If there was incorrect syntax which got fixed during that run, does that count as a linting error? Or, is 1 only returned if errors remain outstanding in the code, after running the tool.

Error 1 is only returned in --lint mode. When running in format mode, syntax is always autocorrected, so an error is never returned.

In theory, if I were to add linting rules that couldn't be autocorrected, then format mode would return 1 if it encountered any of those.

nicklockwood commented 3 years ago

@justinmeiners I've added this to the documentation: https://github.com/nicklockwood/SwiftFormat#error-codes