Tips depend on target shell and yours is unknown. Add a shebang.

Problematic code:

echo "$RANDOM"   # Does this work?

Correct code:

#!/bin/sh
echo "$RANDOM"  # Unsupported in sh. Produces warning.

or

#!/bin/bash
echo "$RANDOM"  # Supported in bash. No warnings.

Rationale:

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.

ShellCheck normally determines your target shell from the shebang (having e.g. #!/bin/sh as the first line). The shell can also be specified from the CLI with -s, e.g. shellcheck -s sh file.

If you don't specify shebang nor -s, ShellCheck gives this message and proceeds with some default (bash).

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 or use -s.

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use $(STATEMENT) instead of legacy `STATEMENT`

Problematic code

echo "Current time: `date`"

Correct code

echo "Current time: $(date)"

Rationale

Backtick command substitution `STATEMENT` is legacy syntax with several issues.

1. It has a series of undefined behaviors related to quoting in POSIX.
2. It imposes a custom escaping mode with surprising results.
3. It's exceptionally hard to nest.

$(STATEMENT) command substitution has none of these problems, and is therefore strongly encouraged.

Exceptions

None.

See also

• http://mywiki.wooledge.org/BashFAQ/082

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use $(STATEMENT) instead of legacy `STATEMENT`

Problematic code

echo "Current time: `date`"

Correct code

echo "Current time: $(date)"

Rationale

Backtick command substitution `STATEMENT` is legacy syntax with several issues.

1. It has a series of undefined behaviors related to quoting in POSIX.
2. It imposes a custom escaping mode with surprising results.
3. It's exceptionally hard to nest.

$(STATEMENT) command substitution has none of these problems, and is therefore strongly encouraged.

Exceptions

None.

See also

• http://mywiki.wooledge.org/BashFAQ/082

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use cd ... || exit in case cd fails.

Problematic code:

cd generated_files
rm -r *.c
 
func(){
  cd foo
  do_something
}

Correct code:

cd generated_files || exit
rm -r *.c
 
# For functions, you may want to use return:
func(){
  cd foo || return
  do_something
}

Rationale:

cd can fail for a variety of reasons: misspelled paths, missing directories, missing permissions, broken symlinks and more.

If/when it does, the script will keep going and do all its operations in the wrong directory. This can be messy, especially if the operations involve creating or deleting a lot of files.

To avoid this, make sure you handle the cases when cd fails. Ways to do this include

• cd foo || exit as suggested to just abort immediately
• if cd foo; then echo "Ok"; else echo "Fail"; fi for custom handling
• <(cd foo && cmd) as an alternative to <(cd foo || exit; cmd) in <(..), $(..) or ( )

Exceptions:

ShellCheck does not give this warning when cd is on the left of a || or &&, or the condition of a if, while or until loop. Having a set -e command anywhere in the script will disable this message, even though it won't necessarily prevent the issue.

If you are accounting for cd failures in a way shellcheck doesn't realize, you can disable this message with a [[directive]].

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.

Problematic code:

make mytarget
 
if [ $? -ne 0 ]
then
  echo "Build failed"
fi

Correct code:

if ! make mytarget
then
  echo "Build failed"
fi

Rationale:

Running a command and then checking its exit status $? against 0 is redundant.

Instead of just checking the exit code of a command, it checks the exit code of a command (e.g. [) that checks the exit code of a command.

Apart from the redundancy, there are other reasons to avoid this pattern:

• Since the command and its status test are decoupled, inserting an innocent command like echo "make finished" after make will cause the if statement to silently start comparing echo's status instead.
• Scripts that run or are called with set -e aka errexit will exit immediately if the command fails, even though they're followed by a clause that handles failure.
• The value of $? is overwritten by [/[[, so you can't get the original value in the relevant then/else block (e.g. if mycmd; then echo "Success"; else echo "Failed with $?"; fi).

To check that a command returns success, use if mycommand; then ....

To check that a command returns failure, use if ! mycommand; then ....

To additionally capture output with command substitution: if output=$(mycommand); then ...

This also applies to while/until loops.

Exceptions:

The default Solaris 10 bourne shell does not support '!' outside of the test command (if ! mycommand; then ... returns !: not found)

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use cd ... || exit in case cd fails.

Problematic code:

cd generated_files
rm -r *.c
 
func(){
  cd foo
  do_something
}

Correct code:

cd generated_files || exit
rm -r *.c
 
# For functions, you may want to use return:
func(){
  cd foo || return
  do_something
}

Rationale:

cd can fail for a variety of reasons: misspelled paths, missing directories, missing permissions, broken symlinks and more.

If/when it does, the script will keep going and do all its operations in the wrong directory. This can be messy, especially if the operations involve creating or deleting a lot of files.

To avoid this, make sure you handle the cases when cd fails. Ways to do this include

• cd foo || exit as suggested to just abort immediately
• if cd foo; then echo "Ok"; else echo "Fail"; fi for custom handling
• <(cd foo && cmd) as an alternative to <(cd foo || exit; cmd) in <(..), $(..) or ( )

Exceptions:

ShellCheck does not give this warning when cd is on the left of a || or &&, or the condition of a if, while or until loop. Having a set -e command anywhere in the script will disable this message, even though it won't necessarily prevent the issue.

If you are accounting for cd failures in a way shellcheck doesn't realize, you can disable this message with a [[directive]].

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.

Problematic code:

make mytarget
 
if [ $? -ne 0 ]
then
  echo "Build failed"
fi

Correct code:

if ! make mytarget
then
  echo "Build failed"
fi

Rationale:

Running a command and then checking its exit status $? against 0 is redundant.

Instead of just checking the exit code of a command, it checks the exit code of a command (e.g. [) that checks the exit code of a command.

Apart from the redundancy, there are other reasons to avoid this pattern:

• Since the command and its status test are decoupled, inserting an innocent command like echo "make finished" after make will cause the if statement to silently start comparing echo's status instead.
• Scripts that run or are called with set -e aka errexit will exit immediately if the command fails, even though they're followed by a clause that handles failure.
• The value of $? is overwritten by [/[[, so you can't get the original value in the relevant then/else block (e.g. if mycmd; then echo "Success"; else echo "Failed with $?"; fi).

To check that a command returns success, use if mycommand; then ....

To check that a command returns failure, use if ! mycommand; then ....

To additionally capture output with command substitution: if output=$(mycommand); then ...

This also applies to while/until loops.

Exceptions:

The default Solaris 10 bourne shell does not support '!' outside of the test command (if ! mycommand; then ... returns !: not found)

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use "${var:?}" to ensure this never expands to /* .

Problematic code:

rm -rf "$STEAMROOT/"*

Correct code:

rm -rf "${STEAMROOT:?}/"*

Rationale:

If STEAMROOT is empty, this will end up deleting everything in the system's root directory.

Using :? will cause the command to fail if the variable is null or unset. Similarly, you can use :- to set a default value if applicable.

In the case command substitution, assign to a variable first and then use :?. This is relevant even if the command seems simple and obviously correct, since forks and execs can fail due to external system limits and conditions, resulting in a blank substitution.

For more details about :? see the "Parameter Expansion" section of the Bash man page.

Exceptions:

None.

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Use "${var:?}" to ensure this never expands to /* .

Problematic code:

rm -rf "$STEAMROOT/"*

Correct code:

rm -rf "${STEAMROOT:?}/"*

Rationale:

If STEAMROOT is empty, this will end up deleting everything in the system's root directory.

Using :? will cause the command to fail if the variable is null or unset. Similarly, you can use :- to set a default value if applicable.

In the case command substitution, assign to a variable first and then use :?. This is relevant even if the command seems simple and obviously correct, since forks and execs can fail due to external system limits and conditions, resulting in a blank substitution.

For more details about :? see the "Parameter Expansion" section of the Bash man page.

Exceptions:

None.

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Consider using { cmd1; cmd2; } >> file instead of individual redirects.

Problematic code:

echo foo >> file
date >> file
cat stuff  >> file

Correct code:

{
  echo foo
  date
  cat stuff
} >> file

Rationale:

Rather than adding >> something after every single line, you can simply group the relevant commands and redirect the group.

Exceptions

This is mainly a stylistic issue, and can freely be ignored.

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.

Double quote to prevent globbing and word splitting.

Problematic code:

echo $1
for i in $*; do :; done # this done and the next one also applies to expanding arrays.
for i in $@; do :; done

Correct code:

echo "$1"
for i in "$@"; do :; done # or, 'for i; do'

Rationale

The first code looks like "print the first argument". It's actually "Split the first argument by IFS (spaces, tabs and line feeds). Expand each of them as if it was a glob. Join all the resulting strings and filenames with spaces. Print the result."

The second one looks like "iterate through all arguments". It's actually "join all the arguments by the first character of IFS (space), split them by IFS and expand each of them as globs, and iterate on the resulting list". The third one skips the joining part.

Quoting variables prevents word splitting and glob expansion, and prevents the script from breaking when input contains spaces, line feeds, glob characters and such.

Strictly speaking, only expansions themselves need to be quoted, but for stylistic reasons, entire arguments with multiple variable and literal parts are often quoted as one:

$HOME/$dir/dist/bin/$file        # Unquoted (bad)
"$HOME"/"$dir"/dist/bin/"$file"  # Minimal quoting (good)
"$HOME/$dir/dist/bin/$file"      # Canonical quoting (good)

When quoting composite arguments, make sure to exclude globs and brace expansions, which lose their special meaning in double quotes: "$HOME/$dir/src/*.c" will not expand, but "$HOME/$dir/src"/*.c will.

Note that $( ) starts a new context, and variables in it have to be quoted independently:

echo "This $variable is quoted $(but this $variable is not)"
echo "This $variable is quoted $(and now this "$variable" is too)"

Exceptions

Sometimes you want to split on spaces, like when building a command line:

options="-j 5 -B"
make $options file

Just quoting this doesn't work. Instead, you should have used an array (bash, ksh, zsh):

options=(-j 5 -B) # ksh: set -A options -- -j 5 -B
make "${options[@]}" file

or a function (POSIX):

make_with_flags() { make -j 5 -B "$@"; }
make_with_flags file

To split on spaces but not perform glob expansion, Posix has a set -f to disable globbing. You can disable word splitting by setting IFS=''.

Similarly, you might want an optional argument:

debug=""
[[ $1 == "--trace-commands" ]] && debug="-x"
bash $debug script

Quoting this doesn't work, since in the default case, "$debug" would expand to one empty argument while $debug would expand into zero arguments. In this case, you can use an array with zero or one elements as outlined above, or you can use an unquoted expansion with an alternate value:

debug=""
[[ $1 == "--trace-commands" ]] && debug="yes"
bash ${debug:+"-x"} script

This is better than an unquoted value because the alternative value can be properly quoted, e.g. wget ${output:+ -o "$output"}.

As always, this warning can be [[ignore]]d on a case-by-case basis.

this is especially relevant when BASH many not be available for the array work around. For example, use in eval or in command options where script has total control of the variables...

FLAGS="-av -e 'ssh -x' --delete --delete-excluded"
...
# shellcheck disable=SC2086
eval rsync $FLAGS ~/dir remote_host:dir

Notice

Original content from the ShellCheck https://github.com/koalaman/shellcheck/wiki.