7x31/shellcheck
1
0
Fork 0
mirror of https://github.com/koalaman/shellcheck.git synced 2025-10-03 19:29:44 +08:00
Code Issues Packages Projects Releases Wiki Activity

Fix caps, highlight code-blocks, and paraphrase a little

John Gardner
2021-12-22 16:04:54 +11:00
parent f28b403c07
commit 23e8cd81f8
1 changed files with 40 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
Integration.md

@@ -1,28 +1,32 @@
# Integrating with ShellCheck
Are you working on an editor linting plugin, a continuous testing tool, a precommit hook or similar, and want to use ShellCheck as a part of it?
Are you working on an editor linting plugin, a continuous testing tool, a pre-commit hook or similar, and want to use ShellCheck as a part of it?
The easiest way is to just invoke `shellcheck`, either on a file or on stdin, and process the json, xml or gcc-style format it can output.
The easiest way is to just invoke `shellcheck`, either on a file or on stdin, and process the JSON, XML or GCC-style format it outputs.
Here is an integration checklist. Each point is described further below:
1. Pick a machine parsable output format: json, xml, gcc or diff
1. Decide whether you want to manually specify a shell dialect
1. Decide whether you want to follow `source`d files that are not specified as input
1. Check `shellcheck`s exit code
1. Allow configuring or passing through the environment variable `SHELLCHECK_OPTS`
1. Consider linking to the wiki for more information about individual errors
1. [__Pick a machine-parsable output format:__](#machine-parsable-output)
* [JSON](#json-output)
* [XML](#xml-output)
* [GCC-style diagnostics](#GCC-compatible-error-messages)
* [Unified diff](#unified-diff)
2. [__Decide whether you want to manually specify a shell dialect__](#specifying-a-shell-dialect)
3. [__Decide whether you want to follow `source`d files that are not specified as input__](#following-inclusions)
4. [__Examine `shellcheck`'s exit code__](#exit-codes)
5. [__Allow configuration or pass-through of the environment variable `SHELLCHECK_OPTS`__](#environment-variables)
6. [__Consider linking to the wiki for more information about individual errors__](#linking-to-the-wiki)
## Pick the output format that makes your life easier
## Machine-parsable output
ShellCheck currently has three machine parseable output formats
ShellCheck currently has three machine-parseable output formats
### JSON output
ShellCheck can output a simple JSON format consisting of an object with a list of comments (formatted for clarity):
```
```console
$ shellcheck -f json1 myscript myotherscript
{
"comments": [
@@ -91,9 +95,9 @@ The legacy format `json` consists of just the `comments` array, with a tab stop
### XML output
ShellCheck can output a CheckStyle compatible XML format:
ShellCheck can output a [CheckStyle](https://checkstyle.sourceforge.io/) compatible XML format:
```
```console
$ shellcheck -f checkstyle myscript myotherscript
<?xml version='1.0' encoding='UTF-8'?>
<checkstyle version='4.3'>
@@ -110,11 +114,11 @@ $ shellcheck -f checkstyle myscript myotherscript
`line` and `column` start at 1, and assume a tab size of 8.
### GCC compatible error messages
### GCC-compatible error messages
If your tool already contains a parser for GCC style error messages, you can have ShellCheck output that:
If your tool already contains a parser for GCC-style error messages, you can have ShellCheck output that:
```
```console
$ shellcheck -f gcc myscript myotherscript
myscript:2:6: warning: In POSIX sh, echo flags are undefined. [SC2039]
myscript:2:9: note: Double quote to prevent globbing and word splitting. [SC2086]
@@ -123,11 +127,11 @@ myotherscript:2:2: error: You need a space after the [ and before the ]. [SC1035
`line` and `column` start at 1, and assume a tab size of 1 (like `gcc` itself).
### Unified Diff
### Unified diff
While ShellCheck's fix suggestions can be found in the `json1` format, it's not well documented or easy to deal with. With `-f diff`, you can instead get standard unified diff output:
While ShellCheck's fix suggestions can be found in the `json1` format, it's not well-documented or easy to deal with. With `-f diff`, you can instead get standard unified diff output:
```
```console
$ shellcheck -f diff file
--- a/file
+++ b/file
@@ -137,7 +141,7 @@ $ shellcheck -f diff file
+echo "$1"
```
## Decide whether you want to specify a shell dialect
## Specifying a shell dialect
If unspecified, ShellCheck will read the shebang, e.g. `#!/bin/sh`, to determine whether to treat the script as a `sh` script, or a `dash` / `bash` / `ksh` script. If no shebang is specified, an /undefined/ default will be used.
@@ -145,39 +149,41 @@ Leaving this to ShellCheck is usually the simplest, easiest and best option.
However, if your tool deals with a lot of files that for any reason have no shebangs, or if it lets the user explicitly set which shell the scripts are intended for, you can specify the dialect with `-s`, e.g. `-s dash` or `-s bash`.
## Decide whether you want to follow `source`d files that are not specified as input
Shell scripts can source/`.`/include arbitrary files. ShellCheck will by default not follow such include statements (unless specified on the command line), in case a hostile script tries to `source /dev/zero` to DoS the system, or `source ~/.ssh/id_rsa` to try to crash with an interesting message.
## Following inclusions
```
Shell-scripts can include arbitrary files by way of the `source` and `.` built-ins. ShellCheck will by default not follow such include statements (unless specified on the command-line), in case a hostile script tries to `source /dev/zero` to DoS the system, or `source ~/.ssh/id_rsa` to try to crash with an interesting message.
```console
$ shellcheck foo
In foo line 2:
source bar
^-- SC1091: Not following: bar was not specified as input (see shellcheck -x).
```
This is useful for remote services like shellcheck.net which accepts arbitrary input from untrusted users, but mostly pointless for e.g. a local editor plugin.
This is useful for remote services like [shellcheck.net](https://www.shellcheck.net/) which accepts arbitrary input from untrusted users, but mostly pointless for e.g. a local editor plugin.
Add `-x` to shellcheck if you would like it to trust the script and follow all includes. To only follow certain includes, add them as file arguments.
Pass `-x` to `shellcheck` if you'd like it to trust the script and follow all includes. To only follow certain includes, add them as file arguments.
## Check `shellcheck`s exit code
## Exit codes
ShellCheck returns useful exit codes:
+ 0: All files successfully scanned with no issues.
+ 1: All files successfully scanned with some issues.
+ 2: Some files could not be processed (e.g. file not found, is a directory).
+ 2: Some files could not be processed (e.g. file not found, is a directory, etc).
+ Other: Bad syntax or options, no point in trying again
## Allow passing through or configuring the environment variable `SHELLCHECK_OPTS`
ShellCheck will look at the environment variable SHELLCHECK_OPTS (space separated arguments to prepend to the command line). Please allow this variable to be passed through from the environment or configured by the user, as it will allow setting additional options both now and in the future.
## Environment variables
## Consider linking to the wiki for more information about individual warnings
ShellCheck will prepend to its command-line any spare-separated arguments found in the environment variable `SHELLCHECK_OPTS` (if defined). Please allow this variable to be passed through from the environment or configured by the user, as it will allow setting additional options both now and in the future.
## Linking to the Wiki
ShellCheck's warnings usually fit on a single line and can therefore be terse.
To provide users with more information, you can construct a wiki link given the error code: `https://www.shellcheck.net/wiki/SC2086` for [SC2086](https://www.shellcheck.net/wiki/SC2086) about unquoted variables. This currently redirects straight to the GitHub wiki.