FSF Tech Team Bash style guide

Thu Sep 12 12:24:20 2024

shellcheck -x -e 2046,2068,2086,2206,2029,2033,2054,2164,2254,2317 SCRIPT_FILE

# 2046 = unquoted $(cmd)
# 2068 = Double quote array expansions to avoid re-splitting elements.
# 2086 = unquoted $var
# 2206 = unquoted $var in array=($var)
# 2254 = unquoted $var in case x in $var)

# 2029 = Using un-escaped variable in ssh call. Reason: This never
  works, warning is generally a false positive.

# 2032 = Warning about calling shell function over ssh. There are ways
  for this to be a false positive, and we generally don't need a warning
  that shellcheck doesn't know if a command exists.

# 2033 = Shell function as argument to another shell. Reason: This never
  works, warning is generally a false positive.

# 2054 = Array declaration contains a comma. Reason: This is warning of a
  mistake based on how other languages work; but commas are not special
  in BASH, and even unquoted, they are legitimate array elements.

# 2164 = `cd` without condition for failure. Reason: We use automatic error
  handling.

# 2317 = Unreachable code. Too many false positives.

# shellcheck disable=SC2035 # justification

tmpstr=$(cmd)
IFS=" " read -r -a array <<<"$tmpstr"

var=$(cmd)
mapfile -t array <<<"$var"

# TODO iank: add x functionality

cat <<END
I have lots
of stuff to say.
END

if x; then
  true
fi
for x; do
  echo 'here $x is $1, then $2, up until $# - 1'
done

if ! test "$BASH_VERSION"; then echo "error: shell is not bash" >&2; exit 1; fi
shopt -s inherit_errexit 2>/dev/null ||: # ignore fail in bash < 4.4
set -eE -o pipefail
trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR

set -e; . /path/to/bash-bear; set +e
test-func() {
  result=true
  echo do stuff
  result=false
}
test-func
$result || echo handling false result

echo this prints too

iptables -D rule || [[ $? == 1 ]] # allow exit code 1 when rule doesn't exist

afunc() { echo ok; "$@"; }

while read -r l; do something; done < <(command-that-could-fail)

tmp=$(mktemp)
command-that-could-fail >$tmp
while read -r l; do something; done <$tmp

echo hello $(command-that-could-fail)

var=$(command-that-could-fail)
echo hello "$var"

for f in $(command-that-could-fail); do true; done
if [[ $(command-that-could-fail) != x ]]; do true; done
local var=$(command-that-could-fail)
declare var=$(command-that-could-fail)
readonly var=$(command-that-could-fail)

local var
var=$(command-that-could-fail)

# Avoid this
x=/s
if (( x )); then
  do something
fi

# Instead, pick one of the following:

# option a:
x=/s
# This will fail due to syntax error.
tmp=$(( x ))
if (( tmp )); then
  do something
fi

# option b:
x=/s
if (( x )); then
  do something
else
  echo some error happened >&2
  exit 1
fi

set -E -o pipefail
trap 'echo "$0:$LINENO:error: \"$BASH_COMMAND\" returned $?" >&2' ERR

ret=0
iptables -D $rule || ret=$?
if [[ $ret != [01] ]]; then
  err-exit exiting due to iptables failure with exit code: $ret
fi

# Constant
readonly conf_dir=/some/path

# Constant and environment
declare -xr conf_dir=/some/path

# A constant set based on condition needs to be set readonly after it's set.
verbose=false
if [[ $1 ]]; then
  verbose=true
fi
readonly verbose

# Prefer this:
addition=$((x + y))
substitution="${string/#foo/bar}"

# Instead of this:
addition="$(expr $x + $y)"
substitution="$(echo "${string}" | sed -e 's/^foo/bar/')"

rm -v -- "$var"
rm -v ./* # a file could be named -rf

[[ $filename == *.png ]] # right-hand globs over left-hand - matches filename with .png extension
# Quote only the right-hand side when globbing is not desired.
[[ $filename == "*.png" ]] # matches filename with literal asterisk "*.png"

usage() {
  cat <<EOF
Usage: ${0##*/} [OPTIONS] ARG1 ARG2
One line description

-b                    Set this boolean option.
-l|--long-opt OPTION  Set this this long option.
-h|--help             Print help and exit.

Note: Uses GNU getopt options parsing style
EOF
  exit $1
}

##### begin command line parsing ########

bool_opt=false
long_opt=foo
temp=$(getopt -l help,long-opt: hbl: "$@") || usage 1
eval set -- "$temp"
while true; do
  case $1 in
    -b) bool_opt=true ;;
    -l|--long-opt) long_opt="$2"; shift ;;
    -h|--help) usage ;;
    --) shift; break ;;
    *) echo "$0: Internal error! unexpected args: $*" ; exit 1 ;;
  esac
  shift
done
arg1="$1"
arg2="$2"
if (( $# != 2 )); then
  echo "$0: error: expected 2 options, got $#." >&2
  exit 1
fi
##### end command line parsing ########

m() { printf "${0##*/}: %s\n"  "$*"; "$@"; }

[[ $EUID == 0 ]] || exec sudo -E "${BASH_SOURCE[0]}" "$@"

this_file="$(readlink -f -- "${BASH_SOURCE[0]}")"
readonly this_file this_dir="${this_file%/*}"
cd "$this_dir"

shopt -s nullglob
for f in dir/*; do
  some-command $f
done

FSF Tech Team Bash style guide

About other documentation

Things mostly relevant to sharing

Shellcheck

Reasons for the exceptions

Other shellcheck issues

Documentation

Code style

Error handling

Automatically exit on failed command:

Gotchas in automatic error handling:

Functions in conditionals

Process Substitution

Command substitution

Arithmetic expressions

Manual error checking

Additional error handling notes:

Good practices

Very common code snippets