linux-workspace/.claude/rules/bash-style.md

paths

paths
**/*.sh bashrc bin/*

Bash Readability Style

The primary goal is code that is easy to understand at a glance. Write bash that reads naturally, follows established conventions, and doesn't require the reader to puzzle over clever tricks. Favor clarity and well-known idioms over brevity.

Complements CLAUDE.md. Does not repeat rules already defined there.

Formatting

• 2-space indentation, no tabs
• then/do on same line: if cond; then / for x in list; do
• Blank lines between logical sections; no blanks between tightly coupled statements
• Long pipe chains: one command per line with leading |

Naming

• UPPER_CASE — exported env vars and constants
• snake_case — local variables and function names
• verb_noun pattern for functions: set_ps1_prompt, docker_aws_login
• Meaningful names, no single letters except loop counters (i, f)

Functions

function do_thing() {
  local name="$1"
  local count="${2:-0}"
  ...
}

• Always function name() { declaration style
• Always local for function variables, assigned on declaration line
• Name parameters immediately: local filename="$1" — no raw $1 in logic
• Default values via ${VAR:-default}
• Guard clauses with early return over deep nesting
• Keep functions focused — single responsibility

Syntax Preferences

• [[ ]] over [ ] for conditionals
• (( )) for arithmetic comparisons
• $(command) for substitution, never backticks
• Double quotes around expansions: "$var", "${array[@]}"
• Single quotes for literals that must not expand
• printf over echo when output contains escapes or format strings

Commands

• Long options for clarity: --recursive not -r (common test flags -f, -d, -e are fine)
• Redirect stderr: > /dev/null 2>&1
• # shellcheck shell=bash at top of sourced (non-executable) files

Comments

• Minimal — explain why, not what
• URL reference when pattern comes from external source
• No banner/divider comments