From d3f3ad1688c6860b196c189186aa40f48ee3bee5 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Tue, 17 Dec 2024 19:56:46 +0000 Subject: [PATCH 1/2] doc(shellcheck): include ignore/enable code list, update usage and doc links --- shellcheck/README.md | 108 +++++++++++++++++++++++++++++++++++++++--- shellcheck/install.sh | 4 ++ 2 files changed, 105 insertions(+), 7 deletions(-) diff --git a/shellcheck/README.md b/shellcheck/README.md index 50c53a401..af8d3cbb8 100644 --- a/shellcheck/README.md +++ b/shellcheck/README.md @@ -14,6 +14,7 @@ These are the files / directories that are created and/or modified with this install: ```text +~/.shellcheckrc ~/.config/envman/PATH.env ~/.local/opt/shellcheck/ ~/.local/bin/shellcheck @@ -32,6 +33,16 @@ Also recommended by Google's shellcheck ./script.sh ``` +With common options: + +```sh +shellcheck \ + -s sh -S style \ + -e SC1090 -e SC1091 \ + -o add-default-case -o deprecate-which \ + scripts/* +``` + ### How to run shellcheck in vim `shellcheck` is @@ -56,20 +67,103 @@ check-scripts: shellcheck myscripts/*.sh ``` -### How to ignore an error +### How to Enable or Ignore Checks + +You can use SCXXXX codes to disable shellcheck errors and warnings at any level +through a variety of means, also described at +, +, and `shellcheck --list-optional`. -You can ignore an error by putting a comment with the `SCXXXX` error code above -it: +**Single Execution** ```sh -# shellcheck disable= +shellcheck -s sh -S style --exclude=SC1090,SC1091 --enable=add-default-case */*.sh ``` +**Single Line** + +(place directly above the offending line) + ```sh -# shellcheck disable=SC1004 -NOT_AN_ERROR='Look, a literal \ -inside of a string!' +# shellcheck disable=SC2016,SC2088 enable=require-variable-braces +echo '~/ is an alias for $HOME' +``` + +**Whole Function** + +(place directly above the function definition) + +```sh +# shellcheck disable=SC2016,SC2088 enable=require-variable-braces +fn_help() { ( + echo '~/ is an alias for $HOME' +); } +``` + +**Whole File** + +(place directly under the shebang, before any expressions) + +```sh +#!/bin/sh +# shellcheck disable=SC1090,SC1091 enable=require-variable-braces +``` + +**Global Process** + +```sh +export SHELLCHECK_OPTS="-e SC1090 -e SC1091 -o deprecate-which" +``` + +**Global Config** + +`~/.shellcheckrc`: + +```sh +disable=SC1090,SC1091 +disable=SC2155 +enable=add-default-case,check-extra-masked-returns,deprecate-which +enable=quote-safe-variables,check-set-e-suppressed,require-variable-braces +``` + +### Common Ignored & Optional Shellcheck Codes + +```text +SC1003 - Want to escape a single quote? echo 'This is how it'\''s done'. +SC1004 - This backslash+linefeed is literal. Break outside single quotes if you just want to break the line. +SC1090 - Can't follow non-constant source. Use a directive to specify location. +SC1091 - Not following: (error message here) # for source .env, etc +SC2005 - Useless `echo`? Instead of `echo $(cmd)`, just use `cmd` +SC2010 - Don't use ls | grep. Use a glob or a for loop with a condition to allow non-alphanumeric filenames. +SC2016 - Expressions don't expand in single quotes, use double quotes for that. +SC2029 - Note that, unescaped, this expands on the client side. +SC2046 - Quote this to prevent word splitting +SC2059 - Don't use variables in the printf format string. Use printf "..%s.." "$foo". +SC2072 - Decimals are not supported. Either use integers only, or use bc or awk to compare. +SC2086 - Double quote to prevent globbing and word splitting. +SC2087 - Quote 'EOF' to make here document expansions happen on the server side rather than on the client. +SC2088 - Tilde does not expand in quotes. Use $HOME. +SC2155 - Declare and assign separately to avoid masking return values. ``` Complete list of `SCXXXX` error codes: + +```text +add-default-case - Suggest adding a default case in `case` statements +avoid-nullary-conditions - Suggest explicitly using -n in `[ $var ]` +check-extra-masked-returns - Check for additional cases where exit codes are masked +check-set-e-suppressed - Notify when set -e is suppressed during function invocation +check-unassigned-uppercase - Warn when uppercase variables are unassigned +deprecate-which - Suggest 'command -v' instead of 'which' +quote-safe-variables - Suggest quoting variables without metacharacters +require-double-brackets - Require [[ and warn about [ in Bash/Ksh +require-variable-braces - Suggest putting braces around all variable references +``` + +Complete list of optional checks: + +```sh +# https://www.shellcheck.net/wiki/optional +shellcheck --list-optional +``` diff --git a/shellcheck/install.sh b/shellcheck/install.sh index 36984c2e9..d0a63c729 100644 --- a/shellcheck/install.sh +++ b/shellcheck/install.sh @@ -20,6 +20,10 @@ __init_shellcheck() { # pkg_install must be defined by every package pkg_install() { + if ! test -e ~/.shellcheckrc; then + touch ~/.shellcheckrc + fi + # ~/.local/opt/shellcheck-v0.99.9/bin mkdir -p "$(dirname "$pkg_src_cmd")" From 5544ff9f1b2fcd514f7de4fb1a374aa661698fa7 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Tue, 17 Dec 2024 20:10:23 +0000 Subject: [PATCH 2/2] feat(shellcheck): include ~/.shellcheckrc with example ignores and enables --- shellcheck/install.sh | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/shellcheck/install.sh b/shellcheck/install.sh index d0a63c729..3889bc1ba 100644 --- a/shellcheck/install.sh +++ b/shellcheck/install.sh @@ -21,7 +21,13 @@ __init_shellcheck() { # pkg_install must be defined by every package pkg_install() { if ! test -e ~/.shellcheckrc; then - touch ~/.shellcheckrc + { + echo '# ignore: https://www.shellcheck.net/wiki/Ignore' + echo '# enable: https://www.shellcheck.net/wiki/optional' + echo '#disable=SC1090,SC1091' + echo '#enable=add-default-case,check-extra-masked-returns,deprecate-which' + echo '#enable=quote-safe-variables,check-set-e-suppressed,require-variable-braces' + } > ~/.shellcheckrc fi # ~/.local/opt/shellcheck-v0.99.9/bin