doc(shellcheck): include common options, update usage and doc links

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
+<https://www.shellcheck.net/wiki/Ignore>,
+<https://www.shellcheck.net/wiki/optional>, 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=<code>
+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:
 <https://gist.github.com/nicerobot/53cee11ee0abbdc997661e65b348f375>
+
+```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
+```

shellcheck/install.sh

@@ -20,6 +20,16 @@ __init_shellcheck() {
 
     # pkg_install must be defined by every package
     pkg_install() {
+        if ! test -e ~/.shellcheckrc; then
+            {
+                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
         mkdir -p "$(dirname "$pkg_src_cmd")"