ShellCheck

Was ShellCheck ist

ShellCheck ist ein statischer Linter für Shell-Skripte: Ein Programm, das den Quellcode liest, analysiert und Probleme meldet, ohne das Skript auszuführen. Es ist in Haskell geschrieben, kostenlos und Open Source unter der GPLv3, gepflegt vom Entwickler Vidar Holen seit 2012.

Der praktische Wert: Erfahrungsgemäß findet ShellCheck den größten Teil der typischen Bash-Bugs, ohne dass auch nur eine Zeile ausgeführt wird. Quoting-Fehler, Word-Splitting-Probleme, falsch verwendete Built-ins, vergessene || exit nach cd — die ganze klassische Fehlerliste deckt der Linter ab. Für jeden gefundenen Punkt liefert er einen SC-Code (z. B. SC2086) mit einer ausführlichen Erklärung im zugehörigen Wiki.

ShellCheck konzentriert sich auf Bash und POSIX-Shell. Für Zsh und Fish ist die Unterstützung minimal — beide Shells haben eigenständige Syntax-Bereiche, die der Linter nicht versteht.

Installation

ShellCheck ist auf allen großen Distributionen paketiert und auch als Standalone-Binary verfügbar.

Wer keinen Root-Zugriff hat oder eine bestimmte Version braucht, lädt die Binaries direkt vom GitHub-Release-Bereich des Projekts. Die Online-Variante ist praktisch für schnelle Checks oder Code-Reviews am fremden Rechner — sie schickt das Skript allerdings über eine fremde Webseite, was bei Skripten mit Firmen-Internas problematisch sein kann.

Verwendung

Der einfachste Aufruf ist shellcheck script.sh. Findet ShellCheck Probleme, listet er sie mit Zeilennummer, SC-Code, Severity und einer kurzen Erklärung.

shellcheck demo.sh

In demo.sh line 4:
cp $datei /backup/
   ^----^ SC2086 (info): Double quote to prevent globbing and word splitting.

Did you mean:
cp "$datei" /backup/

For more information:
  https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent...

Jeder Befund hat einen SC-Code mit eigenem Wiki-Eintrag — dort steht eine ausführliche Erklärung mit Hintergrund, Beispielen und Workarounds. Die Severity-Stufen sind error, warning, info und style. Findet ShellCheck einen Fehler, endet er mit Exit-Code ungleich 0 — perfekt zur Integration in Pre-Commit-Hooks und CI.

Was ShellCheck typisch findet

Eine kleine Auswahl der häufigsten Fundstellen — mit den passenden SC-Codes:

Jeder dieser Fälle ist eine Quelle realer Bugs in Produktion. Besonders SC2086 (fehlende Quotes) ist der Klassiker: In neun von zehn Skripten ohne ShellCheck-Lauf findet sich mindestens eine Stelle, die mit Datei- oder Verzeichnisnamen mit Leerzeichen leise zerbricht.

Konfiguration per Annotation

ShellCheck akzeptiert spezielle Kommentare im Skript, mit denen du das Verhalten lokal oder global steuerst. Sie beginnen alle mit # shellcheck.

#!/usr/bin/env bash
# shellcheck shell=bash

Die shell=-Direktive sagt ShellCheck explizit, welche Shell er annehmen soll. Sinnvoll, wenn der Shebang fehlt oder ungewöhnlich ist (etwa bei Library-Dateien ohne Shebang). Mögliche Werte: bash, sh, dash, ksh, bats.

# shellcheck disable=SC2086
rm $files

Die disable=-Direktive schaltet bestimmte Codes ab — entweder vor einer einzelnen Zeile oder am Anfang der Datei für das ganze Skript. Mehrere Codes durch Komma trennen: disable=SC2086,SC2034.

# shellcheck source=lib/helpers.sh
source "$SCRIPT_DIR/lib/helpers.sh"

ShellCheck folgt source-Anweisungen normalerweise nicht (zu viel Magie mit Variablen-Pfaden). Mit source= zeigst du ihm explizit, welche Datei eingebunden wird — er prüft sie dann mit und versteht die dort definierten Variablen. Pflicht in größeren Projekten mit ausgelagerten Library-Dateien.

Globale Defaults gehen über ~/.shellcheckrc oder .shellcheckrc im Projekt-Root:

# Default: Bash annehmen
shell=bash

# SC2034 immer ignorieren
disable=SC2034

# External sources erlauben
external-sources=true

Diese Datei ist ideal für Team-Projekte: Alle teilen dieselbe Konfiguration, keiner muss sich Flags merken.

Integration in Editor, Pre-Commit und CI

ShellCheck wird erst dann zum echten Helfer, wenn er automatisch läuft — nicht nur, wenn man dran denkt. Drei Ebenen lohnen sich:

Editor. Plugins zeigen Fundstellen direkt im Code mit Unterstreichung und Tooltip:

Pre-Commit-Hook. Ein Skript darf nur ins Repo, wenn ShellCheck zufrieden ist. Klassisch über das Framework pre-commit (Python) oder Husky (Node):

repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.10.0
    hooks:
      - id: shellcheck

CI. In GitHub Actions reicht eine fertige Action:

- name: ShellCheck
  uses: ludeeus/action-shellcheck@master
  with:
    severity: warning

Damit prüft jeder Push und jeder Pull Request automatisch alle Shell-Skripte. Bei einem Fund schlägt der Build fehl — der Bug kann gar nicht erst gemerged werden.

Praxis-Patterns

Die folgenden Aufrufe und Tricks decken den Alltag mit ShellCheck ab.

Erst-Lauf über alle Skripte

shellcheck *.sh

Der Glob expandiert alle .sh-Dateien im aktuellen Verzeichnis. ShellCheck verarbeitet sie alle und meldet Funde aus allen Dateien mit Pfad-Prefix. Erste Anlaufstelle in einem fremden oder gewachsenen Skript-Bestand.

Auf eine Severity einschränken

shellcheck -S error script.sh

Bei einem Skript mit hundert Findings kann es sinnvoll sein, sich erst auf die echten Fehler zu konzentrieren und Style-Hinweise zunächst zu ignorieren. -S akzeptiert error, warning, info und style — die Schwelle filtert alles unterhalb aus.

JSON-Output für Maschinen

shellcheck -f json script.sh | jq '.'

Mit -f json produziert ShellCheck strukturierte Ausgabe statt menschenlesbarem Text — perfekt für CI-Reporter, die Funde aufbereitet darstellen wollen. Weitere Formate: gcc (compatible mit Compiler-Output für Editor-Integration), checkstyle, diff und tty (Default).

Ignore mit Begründung

# shellcheck disable=SC2086 # globbing hier beabsichtigt
rm $files_pattern

Wer eine Regel ausschaltet, sollte immer einen Kommentar dazu schreiben, warum. In sechs Monaten weiß sonst niemand mehr, ob das disable= notwendig oder nur faul war. Der Kommentar nach dem # zählt nicht zur Direktive — er ist normaler Code-Kommentar.

Sourced Libraries explizit angeben

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=lib/helpers.sh
source "$SCRIPT_DIR/lib/helpers.sh"

Der SCRIPT_DIR-Ausdruck ist für ShellCheck zur Analyse-Zeit eine Black Box — er kann dem Pfad nicht selbst folgen. Mit # shellcheck source=lib/helpers.sh zeigst du ihm den Pfad explizit (relativ zum Skript), damit er die Library mitprüft und dort definierte Variablen kennt.

Im Pre-Commit-Hook über alle geänderten Skripte

find . -name '*.sh' -not -path './node_modules/*' -exec shellcheck {} +

Ein einfacher Aufruf, der alle Shell-Skripte im Projekt findet und in einem ShellCheck-Aufruf prüft. -exec ... {} + ist effizienter als \;, weil ShellCheck nur einmal startet und mehrere Dateien auf einmal verarbeitet. Für sehr große Repos lohnt sich git diff --cached --name-only --diff-filter=ACM | grep '\.sh$' | xargs shellcheck, das nur die geänderten Dateien prüft.

Weiterführende Ressourcen

Externe Quellen

• shellcheck.net — Online-Tester direkt im Browser
• GitHub: koalaman/shellcheck — Hauptprojekt mit Releases und Issue-Tracker
• ShellCheck Wiki: SC-Codes — Vollständige Liste aller Checks mit Erklärungen
• shfmt (mvdan/sh) — Begleitender Formatter für Shell-Skripte
• pre-commit Framework — Verwaltung mehrsprachiger Pre-Commit-Hooks

Verwandte Artikel

• Shell-Scripting Debugging — set -x, bash -n und Trace-Strategien
• Shell-Scripting Fehlerbehandlung — set -e, trap und Cleanup-Patterns
• Shell-Scripting Skript-Grundlagen — Shebang, Header und Ausführungsmodi
• Shell-Scripting Funktionen — Funktionen, return und lokale Variablen
• Shell-Scripting Exit-Codes — $?, pipefail und Status-Auswertung