Shellcheck Configuration

1---
2name: shellcheck-configuration
3description: Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
4---
5 
6# ShellCheck Configuration and Static Analysis
7 
8Comprehensive guidance for configuring and using ShellCheck to improve shell script quality, catch common pitfalls, and enforce best practices through static code analysis.
9 
10## Do not use this skill when
11 
12- The task is unrelated to shellcheck configuration and static analysis
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- Setting up linting for shell scripts in CI/CD pipelines
25- Analyzing existing shell scripts for issues
26- Understanding ShellCheck error codes and warnings
27- Configuring ShellCheck for specific project requirements
28- Integrating ShellCheck into development workflows
29- Suppressing false positives and configuring rule sets
30- Enforcing consistent code quality standards
31- Migrating scripts to meet quality gates
32 
33## ShellCheck Fundamentals
34 
35### What is ShellCheck?
36 
37ShellCheck is a static analysis tool that analyzes shell scripts and detects problematic patterns. It supports:
38- Bash, sh, dash, ksh, and other POSIX shells
39- Over 100 different warnings and errors
40- Configuration for target shell and flags
41- Integration with editors and CI/CD systems
42 
43### Installation
44 
45```bash
46# macOS with Homebrew
47brew install shellcheck
48 
49# Ubuntu/Debian
50apt-get install shellcheck
51 
52# From source
53git clone https://github.com/koalaman/shellcheck.git
54cd shellcheck
55make build
56make install
57 
58# Verify installation
59shellcheck --version
60```
61 
62## Configuration Files
63 
64### .shellcheckrc (Project Level)
65 
66Create `.shellcheckrc` in your project root:
67 
68```
69# Specify target shell
70shell=bash
71 
72# Enable optional checks
73enable=avoid-nullary-conditions
74enable=require-variable-braces
75 
76# Disable specific warnings
77disable=SC1091
78disable=SC2086
79```
80 
81### Environment Variables
82 
83```bash
84# Set default shell target
85export SHELLCHECK_SHELL=bash
86 
87# Enable strict mode
88export SHELLCHECK_STRICT=true
89 
90# Specify configuration file location
91export SHELLCHECK_CONFIG=~/.shellcheckrc
92```
93 
94## Common ShellCheck Error Codes
95 
96### SC1000-1099: Parser Errors
97```bash
98# SC1004: Backslash continuation not followed by newline
99echo hello\
100world  # Error - needs line continuation
101 
102# SC1008: Invalid data for operator `=='
103if [[ $var =  "value" ]]; then  # Space before ==
104    true
105fi
106```
107 
108### SC2000-2099: Shell Issues
109 
110```bash
111# SC2009: Consider using pgrep or pidof instead of grep|grep
112ps aux | grep -v grep | grep myprocess  # Use pgrep instead
113 
114# SC2012: Use `ls` only for viewing. Use `find` for reliable output
115for file in $(ls -la)  # Better: use find or globbing
116 
117# SC2015: Avoid using && and || instead of if-then-else
118[[ -f "$file" ]] && echo "found" || echo "not found"  # Less clear
119 
120# SC2016: Expressions don't expand in single quotes
121echo '$VAR'  # Literal $VAR, not variable expansion
122 
123# SC2026: This word is non-standard. Set POSIXLY_CORRECT
124# when using with scripts for other shells
125```
126 
127### SC2100-2199: Quoting Issues
128 
129```bash
130# SC2086: Double quote to prevent globbing and word splitting
131for i in $list; do  # Should be: for i in $list or for i in "$list"
132    echo "$i"
133done
134 
135# SC2115: Literal tilde in path not expanded. Use $HOME instead
136~/.bashrc  # In strings, use "$HOME/.bashrc"
137 
138# SC2181: Check exit code directly with `if`, not indirectly in a list
139some_command
140if [ $? -eq 0 ]; then  # Better: if some_command; then
141 
142# SC2206: Quote to prevent word splitting or set IFS
143array=( $items )  # Should use: array=( $items )
144```
145 
146### SC3000-3999: POSIX Compliance Issues
147 
148```bash
149# SC3010: In POSIX sh, use 'case' instead of 'cond && foo'
150[[ $var == "value" ]] && do_something  # Not POSIX
151 
152# SC3043: In POSIX sh, use 'local' is undefined
153function my_func() {
154    local var=value  # Not POSIX in some shells
155}
156```
157 
158## Practical Configuration Examples
159 
160### Minimal Configuration (Strict POSIX)
161 
162```bash
163#!/bin/bash
164# Configure for maximum portability
165 
166shellcheck \
167  --shell=sh \
168  --external-sources \
169  --check-sourced \
170  script.sh
171```
172 
173### Development Configuration (Bash with Relaxed Rules)
174 
175```bash
176#!/bin/bash
177# Configure for Bash development
178 
179shellcheck \
180  --shell=bash \
181  --exclude=SC1091,SC2119 \
182  --enable=all \
183  script.sh
184```
185 
186### CI/CD Integration Configuration
187 
188```bash
189#!/bin/bash
190set -Eeuo pipefail
191 
192# Analyze all shell scripts and fail on issues
193find . -type f -name "*.sh" | while read -r script; do
194    echo "Checking: $script"
195    shellcheck \
196        --shell=bash \
197        --format=gcc \
198        --exclude=SC1091 \
199        "$script" || exit 1
200done
201```
202 
203### .shellcheckrc for Project
204 
205```
206# Shell dialect to analyze against
207shell=bash
208 
209# Enable optional checks
210enable=avoid-nullary-conditions,require-variable-braces,check-unassigned-uppercase
211 
212# Disable specific warnings
213# SC1091: Not following sourced files (many false positives)
214disable=SC1091
215 
216# SC2119: Use function_name instead of function_name -- (arguments)
217disable=SC2119
218 
219# External files to source for context
220external-sources=true
221```
222 
223## Integration Patterns
224 
225### Pre-commit Hook Configuration
226 
227```bash
228#!/bin/bash
229# .git/hooks/pre-commit
230 
231#!/bin/bash
232set -e
233 
234# Find all shell scripts changed in this commit
235git diff --cached --name-only | grep '\.sh$' | while read -r script; do
236    echo "Linting: $script"
237 
238    if ! shellcheck "$script"; then
239        echo "ShellCheck failed on $script"
240        exit 1
241    fi
242done
243```
244 
245### GitHub Actions Workflow
246 
247```yaml
248name: ShellCheck
249 
250on: [push, pull_request]
251 
252jobs:
253  shellcheck:
254    runs-on: ubuntu-latest
255 
256    steps:
257      - uses: actions/checkout@v3
258 
259      - name: Run ShellCheck
260        run: |
261          sudo apt-get install shellcheck
262          find . -type f -name "*.sh" -exec shellcheck {} \;
263```
264 
265### GitLab CI Pipeline
266 
267```yaml
268shellcheck:
269  stage: lint
270  image: koalaman/shellcheck-alpine
271  script:
272    - find . -type f -name "*.sh" -exec shellcheck {} \;
273  allow_failure: false
274```
275 
276## Handling ShellCheck Violations
277 
278### Suppressing Specific Warnings
279 
280```bash
281#!/bin/bash
282 
283# Disable warning for entire line
284# shellcheck disable=SC2086
285for file in $(ls -la); do
286    echo "$file"
287done
288 
289# Disable for entire script
290# shellcheck disable=SC1091,SC2119
291 
292# Disable multiple warnings (format varies)
293command_that_fails() {
294    # shellcheck disable=SC2015
295    [ -f "$1" ] && echo "found" || echo "not found"
296}
297 
298# Disable specific check for source directive
299# shellcheck source=./helper.sh
300source helper.sh
301```
302 
303### Common Violations and Fixes
304 
305#### SC2086: Double quote to prevent word splitting
306 
307```bash
308# Problem
309for i in $list; do done
310 
311# Solution
312for i in $list; do done  # If $list is already quoted, or
313for i in "${list[@]}"; do done  # If list is an array
314```
315 
316#### SC2181: Check exit code directly
317 
318```bash
319# Problem
320some_command
321if [ $? -eq 0 ]; then
322    echo "success"
323fi
324 
325# Solution
326if some_command; then
327    echo "success"
328fi
329```
330 
331#### SC2015: Use if-then instead of && ||
332 
333```bash
334# Problem
335[ -f "$file" ] && echo "exists" || echo "not found"
336 
337# Solution - clearer intent
338if [ -f "$file" ]; then
339    echo "exists"
340else
341    echo "not found"
342fi
343```
344 
345#### SC2016: Expressions don't expand in single quotes
346 
347```bash
348# Problem
349echo 'Variable value: $VAR'
350 
351# Solution
352echo "Variable value: $VAR"
353```
354 
355#### SC2009: Use pgrep instead of grep
356 
357```bash
358# Problem
359ps aux | grep -v grep | grep myprocess
360 
361# Solution
362pgrep -f myprocess
363```
364 
365## Performance Optimization
366 
367### Checking Multiple Files
368 
369```bash
370#!/bin/bash
371 
372# Sequential checking
373for script in *.sh; do
374    shellcheck "$script"
375done
376 
377# Parallel checking (faster)
378find . -name "*.sh" -print0 | \
379    xargs -0 -P 4 -n 1 shellcheck
380```
381 
382### Caching Results
383 
384```bash
385#!/bin/bash
386 
387CACHE_DIR=".shellcheck_cache"
388mkdir -p "$CACHE_DIR"
389 
390check_script() {
391    local script="$1"
392    local hash
393    local cache_file
394 
395    hash=$(sha256sum "$script" | cut -d' ' -f1)
396    cache_file="$CACHE_DIR/$hash"
397 
398    if [[ ! -f "$cache_file" ]]; then
399        if shellcheck "$script" > "$cache_file" 2>&1; then
400            touch "$cache_file.ok"
401        else
402            return 1
403        fi
404    fi
405 
406    [[ -f "$cache_file.ok" ]]
407}
408 
409find . -name "*.sh" | while read -r script; do
410    check_script "$script" || exit 1
411done
412```
413 
414## Output Formats
415 
416### Default Format
417 
418```bash
419shellcheck script.sh
420 
421# Output:
422# script.sh:1:3: warning: foo is referenced but not assigned. [SC2154]
423```
424 
425### GCC Format (for CI/CD)
426 
427```bash
428shellcheck --format=gcc script.sh
429 
430# Output:
431# script.sh:1:3: warning: foo is referenced but not assigned.
432```
433 
434### JSON Format (for parsing)
435 
436```bash
437shellcheck --format=json script.sh
438 
439# Output:
440# [{"file": "script.sh", "line": 1, "column": 3, "level": "warning", "code": 2154, "message": "..."}]
441```
442 
443### Quiet Format
444 
445```bash
446shellcheck --format=quiet script.sh
447 
448# Returns non-zero if issues found, no output otherwise
449```
450 
451## Best Practices
452 
4531. **Run ShellCheck in CI/CD** - Catch issues before merging
4542. **Configure for your target shell** - Don't analyze bash as sh
4553. **Document exclusions** - Explain why violations are suppressed
4564. **Address violations** - Don't just disable warnings
4575. **Enable strict mode** - Use `--enable=all` with careful exclusions
4586. **Update regularly** - Keep ShellCheck current for new checks
4597. **Use pre-commit hooks** - Catch issues locally before pushing
4608. **Integrate with editors** - Get real-time feedback during development
461 
462## Resources
463 
464- **ShellCheck GitHub**: https://github.com/koalaman/shellcheck
465- **ShellCheck Wiki**: https://www.shellcheck.net/wiki/
466- **Error Code Reference**: https://www.shellcheck.net/
467