4.0 | Document the new (and old) exit codes and the ignore_non_auto_fixable_on_exit flag

Author: jrfnl

wiki/Advanced-Usage.md

@@ -18,6 +18,7 @@
     * [The Level Map](#the-level-map)
 * [Printing Verbose Token Processing Output](#printing-verbose-token-processing-output)
 * [Quieting Output](#quieting-output)
+* [Understanding the Exit Codes](#understanding-the-exit-codes)
 
 ***
 
@@ -524,3 +525,35 @@ For example, the ScopeIndentSniff executes on the if statement's token only, but
 If a coding standard or configuration file includes settings to print progress or verbose output while running PHP_CodeSniffer, it can make it difficult to use the standard with automated checking tools and build scripts as these typically only expect an error report. If you have this problem, or just want less output, you can quieten the output of PHP_CodeSniffer by using the `-q` command line argument. When using this quiet mode, PHP_CodeSniffer will only print report output, and only if errors or warnings are found. No progress or verbose output will be printed.
 
 <p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
+## Understanding the Exit Codes
+
+As of PHP_CodeSniffer 4.0.0, exit codes are cumulative and composed as follows:
+
+| Exit code | Meaning                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------- |
+| `0`       | clean code base / successful non-scan request (_help/documentation/etc_)                                |
+| `1`       | issues found/remaining, auto-fixable                                                                    |
+| `2`       | issues found/remaining, non-auto-fixable                                                                |
+| `4`       | failure to fix some files/fixer conflict (phpcbf only)                                                  |
+| `16`      | processing error - blocking the actual run of PHP_CodeSniffer, like a parse error in an XML ruleset     |
+| `64`      | requirements for running not met (i.e. minimum PHP version doesn't comply, missing required extensions) |
+
+Example: when running `phpcs`, if both auto-fixable as well as non-auto-fixable issues are found, the exit code will be `3` (`1` + `2`).
+
+The exit codes can be influenced by the following configuration flags: [`ignore_errors_on_exit`](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#ignoring-errors-when-generating-the-exit-code), [`ignore_warnings_on_exit`](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#ignoring-warnings-when-generating-the-exit-code) and [`ignore_non_auto_fixable_on_exit`](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#ignoring-non-auto-fixable-issues-when-generating-the-exit-code).
+
+
+In PHP_CodeSniffer 3.x, the exit codes were:
+
+| `phpcs` |                      | `phpcbf` |                                                          |
+| ------- | -------------------- | -------- | -------------------------------------------------------- |
+| `0`     | no errors found      | `0`      | no fixable errors were found, so nothing was fixed       |
+| `1`     | errors found         | `1`      | all fixable errors were fixed correctly                  |
+| `2`     | fixable errors found | `2`      | PHPCBF failed to fix some of the fixable errors it found |
+| `3`     | processing error     | `3`      | processing error                                         |
+
+And the following configuration flags were available: [`ignore_errors_on_exit`](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#ignoring-errors-when-generating-the-exit-code), [`ignore_warnings_on_exit`](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Configuration-Options#ignoring-warnings-when-generating-the-exit-code).
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>

wiki/Configuration-Options.md

@@ -13,6 +13,7 @@
 * [Setting the PHP version](#setting-the-php-version)
 * [Ignoring errors when generating the exit code](#ignoring-errors-when-generating-the-exit-code)
 * [Ignoring warnings when generating the exit code](#ignoring-warnings-when-generating-the-exit-code)
+* [Ignoring non-auto-fixable issues when generating the exit code (PHP_CodeSniffer >= 4.0.0)](#ignoring-non-auto-fixable-issues-when-generating-the-exit-code-php_codesniffer--400)
 * Setting tool paths
     * [CSSLint](#setting-the-path-to-csslint)
     * [Google Closure Linter](#setting-the-path-to-the-google-closure-linter)
@@ -235,6 +236,19 @@ $ phpcs --config-set ignore_warnings_on_exit 1
 <p align="right"><a href="#table-of-contents">back to top</a></p>
 
 
+## Ignoring non-auto-fixable issues when generating the exit code (PHP_CodeSniffer >= 4.0.0)
+
+By default, PHP_CodeSniffer will exit with a non-zero code if any errors or warnings are found, whethere these are auto-fixable or not.
+If you want to display non-autofixable errors and warnings to the user, but still return with a zero exit code if non-auto-fixable issues are found, you can set the `ignore_non_auto_fixable_on_exit` configuration option.
+This option is typically used by automated build tools so that a `phpcbf` run can exit with `0` if it fixed all fixable issues, but there are still some non-auto-fixable issues remaining.
+
+```bash
+$ phpcs --config-set ignore_non_auto_fixable_on_exit 1
+```
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
 ## Generic Coding Standard Configuration Options
 
 ### Setting the path to CSSLint