gentleman-guardian-angel

name	gentleman-guardian-angel
description	Maintain shell script quality and portability across all GGA bash scripts. Use when this capability is needed.
metadata	{"author":"Gentleman-Programming"}

Skill: gga-shellcheck-standards

Purpose

Maintain shell script quality and portability across all GGA bash scripts.

When to Use

When writing or modifying bash scripts in bin/ or lib/.

Running ShellCheck

# Via make (preferred)
make lint

# Direct (matches CI configuration)
shellcheck -x -e SC1090,SC1091,SC2162,SC2129 bin/gga lib/*.sh

All new code must pass make lint before pushing.

Accepted Exclusions

Code	Rule	Why GGA Excludes It
SC1090	Can't follow non-constant source	GGA uses dynamic paths for lib loading
SC1091	Not following sourced file	Same — dynamic lib sourcing
SC2162	read without -r	GGA intentionally handles backslash input
SC2129	Use { } >> file	Style preference — individual redirects are clearer here

Do NOT add new exclusions without justification in a PR comment.

Critical Rules

Quoting

# GOOD — always quote variables
echo "$var"
"$cmd" "$arg"

# BAD — unquoted
echo $var
$cmd $arg

Conditionals

# GOOD — use [[ ]] in bash
[[ "$var" == "value" ]]
[[ -f "$file" ]]

# BAD — use [ ] only for POSIX compatibility
[ "$var" = "value" ]

Function Variables

# GOOD — always local
my_function() {
  local result
  result="something"
}

# BAD — leaks to global scope
my_function() {
  result="something"
}

No eval

# BAD — never
eval "$user_input"

# If you think you need eval, you don't. Use arrays or parameter expansion.

macOS vs Linux Portability

# sed -i behaves differently
# macOS requires an extension (even empty string)
sed -i '' 's/foo/bar/' file        # macOS
sed -i 's/foo/bar/' file           # Linux

# GGA pattern — detect and branch:
if [[ "$OSTYPE" == "darwin"* ]]; then
  sed -i '' 's/foo/bar/' "$file"
else
  sed -i 's/foo/bar/' "$file"
fi

Common Fixes

ShellCheck warning	Fix
SC2086: double quote	Add "$var" around the variable
SC2181: check $?	Replace if [ $? -eq 0 ] with if command; then
SC2155: declare + assign	Split: local var; var=$(cmd)
SC2206: word splitting	Use read -ra arr <<< "$str"

Cookbook

If...	Then...
Writing a new function	Add local for every variable, quote every expansion
Using sed -i	Add macOS/Linux compatibility check
Reading user input	Use read -r unless backslash handling is intentional
Writing a loop over files	Use while IFS= read -r line or glob, never ls

---

Source: Gentleman-Programming/gentleman-guardian-angel — distributed by TomeVault.