google-shell-style

What this skill does

# Google Shell Style Guide

Apply consistent, safe, and readable shell scripting practices based on Google's Shell Style Guide.

## Core Principles

1. **Consistency** - Follow existing style in files being modified
2. **Safety** - Quote variables, use `[[ ]]`, avoid `eval`
3. **Readability** - 2-space indent, 80-char lines, clear naming

## Quick Reference

| Rule | Do | Avoid |
|------|-----|-------|
| Command substitution | `$(command)` | `` `command` `` |
| Tests | `[[ condition ]]` | `[ condition ]` or `test` |
| Arithmetic | `(( x + y ))` | `let`, `expr`, `$[ ]` |
| Variables | `"${var}"` | `$var` or `${var}` unquoted |
| Functions | `func_name() {` | `function func_name {` |
| Indentation | 2 spaces | Tabs |

## Formatting Rules

### Indentation

Use 2 spaces. Never tabs (exception: heredoc with `<<-`).

```bash
if [[ -n "${var}" ]]; then
  echo "indented with 2 spaces"
fi
```

### Line Length

Maximum 80 characters. For long strings, use heredocs or embedded newlines:

```bash
cat <<EOF
Long string content
spanning multiple lines
EOF

long_string="First line
second line"
```

### Pipelines

One line if fits, otherwise split with pipe on new line:

```bash
command1 | command2

command1 \
  | command2 \
  | command3
```

### Control Flow

Put `; then` and `; do` on same line as `if`/`for`/`while`:

```bash
if [[ -d "${dir}" ]]; then
  process_dir
fi

for file in "${files[@]}"; do
  process_file "${file}"
done

while read -r line; do
  echo "${line}"
done < input.txt
```

### Case Statements

Indent alternatives by 2 spaces. Simple cases on one line:

```bash
case "${option}" in
  a) action_a ;;
  b) action_b ;;
  complex)
    do_something
    do_more
    ;;
  *)
    error "Unknown option"
    ;;
esac
```

## Variable Handling

### Quoting

Always quote strings containing variables, command substitutions, or special characters:

```bash
flag="$(some_command)"
echo "${flag}"
grep -li Hugo /dev/null "$1"
```

### Variable Expansion

Prefer `"${var}"` with braces. Exception: single-character positional params (`$1`, `$@`):

```bash
echo "PATH=${PATH}, file=${filename}"
echo "Positional: $1 $2 $3"
echo "All args: $@"
```

### Arrays

Use arrays for lists, especially command arguments:

```bash
declare -a flags
flags=(--foo --bar='baz')
flags+=(--config="${config_file}")
mybinary "${flags[@]}"
```

## Command Substitution and Tests

### Command Substitution

Always use `$(command)`, never backticks:

```bash
var="$(command "$(nested_command)")"
```

### Tests

Use `[[ ]]` for all tests. Use `-z`/`-n` for string checks, `(( ))` for numeric:

```bash
if [[ -z "${my_var}" ]]; then
  echo "empty"
fi

if [[ "${my_var}" == "value" ]]; then
  echo "match"
fi

if (( count > 10 )); then
  echo "large"
fi
```

### Arithmetic

Use `(( ))` or `$(( ))`. Never `let`, `expr`, or `$[ ]`:

```bash
(( i += 3 ))
result=$(( x * y + z ))

if (( a < b )); then
  echo "a is smaller"
fi
```

## Naming Conventions

### Functions

Lowercase with underscores. Braces on same line:

```bash
my_function() {
  local result
  result="$(do_work)"
  echo "${result}"
}

mypackage::helper() {
  # namespaced function
}
```

### Variables

Lowercase with underscores for local variables:

```bash
local file_name
local -i count=0
```

### Constants

Uppercase with underscores. Use `readonly`:

```bash
readonly CONFIG_PATH='/etc/app/config'
declare -xr EXPORTED_VAR='value'
```

## Script Structure

### Function Location

Put all functions near top, after constants. No executable code between functions.

### Main Function

Scripts with multiple functions must have a `main` function:

```bash
#!/bin/bash

readonly SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

helper_func() {
  # helper implementation
}

main() {
  local arg="$1"
  helper_func "${arg}"
}

main "$@"
```

### Local Variables

Always declare function variables as `local`. Separate declaration from command substitution:

```bash
my_func() {
  local name="$1"
  local result
  result="$(some_command)"
  (( $? == 0 )) || return 1
  echo "${result}"
}
```

## Common Anti-Patterns

### Avoid eval

```bash
eval $(set_my_variables)
```

### Avoid Aliases in Scripts

Use functions instead:

```bash
fancy_ls() {
  ls -lh "$@"
}
```

### Avoid Pipes to While

Use process substitution to preserve variables:

```bash
while read -r line; do
  last_line="${line}"
done < <(your_command)
```

### Avoid mapfile/readarray (macOS Incompatible)

`mapfile` and `readarray` are Bash 4+ builtins not available on macOS (Bash 3.2). Use `while read` loop instead:

```bash
# AVOID - fails on macOS
mapfile -t files < <(find . -name "*.txt")

# USE - portable
files=()
while IFS= read -r file; do
  files+=("$file")
done < <(find . -name "*.txt")
```

### Wildcard Safety

Use explicit path prefix:

```bash
rm -v ./*
```

## Error Handling

### Check Return Values

```bash
if ! mv "${files[@]}" "${dest}/"; then
  echo "Move failed" >&2
  exit 1
fi
```

### PIPESTATUS

Check pipeline component failures:

```bash
tar -cf - ./* | ( cd "${dir}" && tar -xf - )
if (( PIPESTATUS[0] != 0 || PIPESTATUS[1] != 0 )); then
  echo "Pipeline failed" >&2
fi
```

## Security Patterns

### Safe Temporary Files

Always use `mktemp` with trap cleanup:

```bash
cleanup() {
  local exit_code=$?
  [[ -n "${TEMP_FILE:-}" ]] && rm -f "${TEMP_FILE}"
  exit "${exit_code}"
}
trap cleanup EXIT

TEMP_FILE="$(mktemp)"
# use TEMP_FILE...
```

### Input Validation

Validate user input before use:

```bash
validate_path() {
  local path="$1"
  # Reject empty
  [[ -z "${path}" ]] && return 1
  # Reject path traversal
  [[ "${path}" == *..* ]] && return 1
  # Require within allowed directory
  [[ "${path}" != "${ALLOWED_DIR}"/* ]] && return 1
  return 0
}
```

### Command Injection Prevention

Never use `eval` with external input. Use arrays for dynamic commands:

```bash
# DANGEROUS - injection risk
eval "${user_command}"

# SAFE - use arrays
declare -a cmd_args
cmd_args=("--flag" "${user_input}")
mycommand "${cmd_args[@]}"
```

Always quote variable expansions in commands:

```bash
# DANGEROUS
rm $file_path
grep $pattern $file

# SAFE
rm -- "${file_path}"
grep -- "${pattern}" "${file}"
```

Use `--` to prevent option injection with user-provided filenames.

## Issue Severity Classification

For shell-expert agent reviews, issues are classified as:

### Critical (Must Fix)

- Unquoted variables in `rm`, `mv`, or path operations
- Use of `eval` with external input
- Missing error handling on destructive operations
- Command injection vulnerabilities

### Important (Should Fix)

- Using `[ ]` instead of `[[ ]]`
- Missing `local` in functions
- Backticks instead of `$()`
- Missing `main` function in multi-function scripts

### Minor (Suggestions)

- Inconsistent indentation
- Long lines (> 80 chars)
- Missing braces on simple variables
- Comment formatting

## Additional Resources

For the complete Google Shell Style Guide, see: https://google.github.io/styleguide/shellguide.html