Revert 1d391cdfaeb382f2236cae11d021797a608d17aa...5655bd6102db4a819238fb4973bd569ce80f5f70 on SC2148

SC2148.md

@@ -1,18 +1,39 @@
-Add a shebang line to the top of your script:
+##  Tips depend on target shell and yours is unknown. Add a shebang.
 
-```bash
+### Problematic code:
+
+```sh
+echo "$RANDOM"   # Does this work?
+```
+
+### Correct code:
+
+```sh
+#!/bin/sh
+echo "$RANDOM"  # Unsupported in sh. Produces warning.
+```
+
+or
+
+```sh
 #!/bin/bash
+echo "$RANDOM"  # Supported in bash. No warnings.
 ```
 
-Or, for scripts that will not be executed (*e.g.*, `~/.bashrc`), use a directive:
+### Rationale:
 
-```bash
-# shellcheck shell=bash
-```
+Different shells support different features. To give effective advice, ShellCheck needs to know which shell your script is going to run on. You will get a different numbers of warnings about different things depending on your target shell.
 
-If neither of those options are possible or desirable, you can invoke ShellCheck with the `--shell` switch:
-```bash
-shellcheck --shell=sh without-shebang.sh
-```
+If you add a shebang (e.g. `#!/bin/bash` as the first line), the OS will use this interpreter when the script is executed, and ShellCheck will use this shell when offering advice.
 
-See `shellcheck --help` for a list of supported flavors (sh, bash, dash, ksh).
+If you for any reason can't or won't add a shebang, there are multiple other ways to let shellcheck know which shell you're coding for:
+
+* Specify the shell using the `-s` or `--shell` flag, e.g. `shellcheck -s bash myfile`
+* Use a shellcheck [[directive]], adding `# shellcheck shell=ksh` before the first command in the file.
+* Give the script a `.bash`, `.ksh` or `.dash` extension (`.sh` will not assume `--shell=sh` since it's so generic)
+
+Note that this error can not be ignored with a [[directive]]. It is not a suggestion to improve your script, but a warning that ShellCheck lacks information it needs to be helpful.
+
+### Exceptions
+
+None. Please either add a shebang, directive, extension or use `-s`.