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

General visual layout with some editorial and addition of --rcfile

©TriMoon™
2025-01-13 21:52:35 +03:00
parent 17bbd4670e
commit 9686369d81
1 changed files with 233 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
Directive.md

@@ -1,6 +1,30 @@
# ShellCheck Directives - [`shellcheck` directives](#shellcheck-directives)
- [Documenting directive use](#documenting-directive-use)
- [`.shellcheckrc` file](#shellcheckrc-file)
- [Supported directives](#supported-directives)
- [disable](#disable)
- [enable](#enable)
- [external-sources](#external-sources)
- [source](#source)
- [source-path](#source-path)
- [shell](#shell)
- [Supported options](#supported-options)
- [--rcfile](#--rcfile)
- [others](#others)
Shellcheck directives allow you to control how `shellcheck` works, and take the form of comments in files: ## `shellcheck` directives
Shellcheck directives allow you to control how `shellcheck` works, and can be added:
1. As entries in a [`.shellcheckrc` file](#shellcheckrc-file) in the project's root-, or user's home-, directory:
```sh
# Don't suggest [ -n "$VAR" ] over [ ! -z "$VAR" ]
disable=SC2236
# Suggest ${VAR} in place of $VAR
enable=require-variable-braces
```
1. and/Or as comments inside individual script files:
```sh ```sh
hexToAscii() { hexToAscii() {
@@ -9,94 +33,10 @@ hexToAscii() {
} }
``` ```
or entries in a `.shellcheckrc` in the project root or user's home directory: Directives that replace or are immediately after the shebang apply to the entire script.\
Otherwise, they are scoped to the command that follows it. _(including compound commands like function definitions, loops and case statements)_
```none - A directive may only be applied to a complete command, and can not be used immediately preceding an `else` block or individual `case` branch:
$ cat ~/.shellcheckrc
# Don't suggest [ -n "$VAR" ] over [ ! -z "$VAR" ]
disable=SC2236
# Suggest ${VAR} in place of $VAR
enable=require-variable-braces
```
## Supported directives
### disable
Prevent shellcheck from processing one or more warnings:
```sh
# shellcheck disable=code[,code...]
statement_where_warning_should_be_disabled
```
A range of errors can also be specified, handy when disbaling things for the entire file.
```sh
#!/bin/bash
# shellcheck disable=SC1000-SC9999
```
### enable
Enables an [[optional]] check (since 0.7.0).
```sh
#!/bin/bash
# shellcheck enable=require-variable-braces
echo "Hello $USER" # Will suggest ${USER}
```
To see a list of optional checks with examples, run `shellcheck --list-optional`. See [[here|optional]] for more information.
### external-sources
Set whether or not to follow arbitrary file paths in `source` statements (since 0.8.0).
Use `external-sources=true` in `.shellcheckrc` to let shellcheck access arbitrary files, whether or not they're specified as input. `external-sources=false` disables this, which is the default.
Individual script files can disable but not enable this option.
### source
Tell ShellCheck where to find a sourced file (since 0.4.0):
```sh
# shellcheck source=src/examples/config.sh
. "$(locate_config)"
```
### source-path
Give ShellCheck a path in which to search for sourced file (since 0.7.0).
```sh
# The script will now look for src/examples/mylib.sh
# shellcheck source-path=src/examples
. mylib.sh
```
The special value `source-path=SCRIPTDIR` will search in the current script's directory, and it can be used as a relative path like `source-path=SCRIPTDIR/../lib`.
To support the common pattern of `. "$CONFIGDIR/mylib.sh"`, ShellCheck strips one leading, dynamic section before trying to locate the rest. That means that ShellCheck will look for `config.sh` and `utils.sh` in the same directory as this script when it is being checked:
```sh
#!/bin/sh
# shellcheck source-path=SCRIPTDIR
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
. "$here/config.sh"
. "$here/utils.sh"
```
### shell
Specify the shell for a script (similar to the shebang, if you for any reason don't want to add one) (since [0.4.5](https://github.com/koalaman/shellcheck/issues/581#issuecomment-249437837)):
```sh
# shellcheck shell=sh
echo foo &> bar
```
Directives that replace or are immediately after the shebang apply to the entire script. Otherwise, they are scoped to the command that follows it (including compound commands like function definitions, loops and case statements). A directive may only be applied to a complete command, and can not be used immediately preceding an `else` block or individual `case` branch:
```sh ```sh
# Directive VALID here, applies to whole `case` # Directive VALID here, applies to whole `case`
@@ -115,7 +55,8 @@ case $1 in
esac esac
``` ```
There is no support for scoping a directive to the first structure of the script. In these cases, use a dummy command `true` or `:` and then add directives, such as - There is no support for scoping a directive to the first structure of the script.\
In these cases, use a dummy command like `true` or `:` and then add the directives, such as:
```sh ```sh
# This directive applies to the entire script # This directive applies to the entire script
@@ -129,13 +70,12 @@ f() {
} }
``` ```
Silencing parser errors is purely cosmetic; any parser error found will still stop ShellCheck at the point of the error. ### Documenting directive use
## Documenting directive use It is recommended to add a comment to document why a specific directive was used.
To document why a specific directive was used, it is recommended to add a comment. - The comment can be added on the preceding line.\
_(This is the recommended style for long comments.)_
The comment can be added on the preceding line. This is the recommended option for long comments.
```sh ```sh
# this is intentional because of reasons # this is intentional because of reasons
@@ -144,9 +84,191 @@ The comment can be added on the preceding line. This is the recommended option f
statement_where_warning_should_be_disabled statement_where_warning_should_be_disabled
``` ```
The comment can also be added at the end of the directive line. This is the recommended option for short comments. - The comment can also be added at the end of the directive line.\
_(This is the recommended style for short comments.)_
s
```sh ```sh
# shellcheck disable=SC1234 # this is intentional # shellcheck disable=SC1234 # this is intentional
statement_where_warning_should_be_disabled statement_where_warning_should_be_disabled
``` ```
### `.shellcheckrc` file
Unless the `--norc` option is used;
- `shellcheck` will look for a file named `.shellcheckrc` or `shellcheckrc` _(note without the dot)_,\
in the script's directory and each parent directory of that.\
If it is not found there, it will look for it in the user's `HOME` directory (fe. `~/.shellcheckrc`),\
followed by the `XDG config` directory.\
(usually `~/.config/shellcheckrc` on Unix, or `%APPDATA%/shellcheckrc` on Windows)
Only the first-found file will be used.
- If found, it will read `key=value` pairs from it and treat them as **_file-wide_ directives**.\
Example `.shellcheckrc` looks like:
```sh
# Look for 'source'd files relative to the checked script,
# and also look for absolute paths in /mnt/chroot
source-path=SCRIPTDIR
source-path=/mnt/chroot
# Since 0.9.0, values can be quoted with '' or "" to allow spaces
source-path="My Documents/scripts"
# Allow opening any 'source'd file, even if not specified as input
external-sources=true
# Turn on warnings for unquoted variables with safe values
enable=quote-safe-variables
# Turn on warnings for unassigned uppercase variables
enable=check-unassigned-uppercase
# Allow [ ! -z foo ] instead of suggesting -n
disable=SC2236
```
- ℹ️Note for **Snap** users:\
The Snap sandbox disallows access to hidden files.\
Use `shellcheckrc` without the dot instead.
- ℹ️Note for **Docker** users:\
`shellcheck` will only be able to look for files that
are **mounted in the container**, so `~/.shellcheckrc` can not be accessed nor read.
### Supported directives
- [disable](#disable)
- [enable](#enable)
- [external-sources](#external-sources)
- [source](#source)
- [source-path](#source-path)
- [shell](#shell)
#### disable
- **4-digits** _(with or without `SC` prefixed)_\
_Prevents `shellcheck` from processing one or more warnings:_
```sh
# shellcheck disable=code[,code...]
statement_where_warning_should_be_disabled
```
- A **range** can also be specified, handy when disabaling multiple warnings/errors for the entire file.
```sh
#!...
# shellcheck disable=SC1000-SC9999
# shellcheck disable=1000-9999
```
ℹ️Silencing parser errors is purely cosmetic; Any parser error found will still stop `shellsheck` at the point of the error.
#### enable
[optional checks]: https://github.com/koalaman/shellcheck/wiki/Optional
- **keyphrase**\
(since 0.7.0)\
_Enables one or more [optional checks]._
```sh
#!...
# shellcheck enable=require-variable-braces
echo "Hello $USER" # Will suggest to change into ${USER}
```
- To see a list of [optional checks] with examples, run:
```console
shellcheck --list-optional
```
#### external-sources
- **boolean** (true|false|0|1)\
(since v0.8.0)\
_Allows or disallows `shellcheck` to include the files pointed-to by the `source` or `.` statements while checking._\
`external-sources=false` disables this, which is the default.
- In `.shellcheckrc` set `external-sources=true` to enable it globally.\
_(Individual script files can **disable** but not enable this option.)_
#### source
- **single filename** (with or without a leading path)\
(since v0.4.0)\
_Dictates `shellcheck` where to find the to-be-sourced file._
```sh
# shellcheck source=src/examples/config.sh
. "$(locate_config)"
```
- see `SCRIPTDIR` in [source-path](#source-path) (since v0.7.0)?
```sh
# shellcheck source=SCRIPTDIR/examples/config.sh
source "${my_SCRIPTDIR}/config.sh"
```
```sh
#!...
# shellcheck source-path=SCRIPTDIR/examples
...
source config.sh
```
#### source-path
- **filepath** (absolute or relative)\
(since 0.7.0)\
_Informs `shellcheck` where to search for sourced files_.
```sh
# The script will now look for src/examples/mylib.sh
# shellcheck source-path=src/examples
. mylib.sh
```
- The special value `SCRIPTDIR` will search in the current script's directory, and it can be used as a relative path like `SCRIPTDIR/../lib`.\
To support the common pattern of `"${SOME_VAR_NAME}/mylib.sh"`, `shellcheck` strips one leading, dynamic section, before trying to locate the rest.\
That means that `shellcheck` will look for `config.sh` and `utils.sh` in the same directory as the script itself when it is being checked in the below example:
```sh
#!...
# shellcheck source-path=SCRIPTDIR
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
. "$here/config.sh"
. "$here/utils.sh"
```
#### shell
- **type of shell** (sh|bash||...)\
(since [v0.4.5](https://github.com/koalaman/shellcheck/issues/581#issuecomment-249437837))\
_Specifies the shell dialect for a script._
This is similar to a _shebang_/_hashbang/etc_, if you for any reason don't want to add one.
```sh
# shellcheck shell=sh
echo foo &> bar
```
### Supported options
#### --rcfile
- **filepath**\
(since [v0.10.0](https://github.com/koalaman/shellcheck/pull/2908))\
_Dictates `shellcheck` to prefer the specified configuration file, instead of searching for one in the default locations first._
See [`.shellcheckrc` file](#shellcheckrc-file) for the contents of this file.
#### others
- For a listing of other options not mentioned here, and actually supported by your version of `shellcheck`, try one or both of these commands: 😉
```console
man shellcheck
```
```console
shellcheck --help
```