lpic-sim/ai/common/bash.md

Bash-Standard (verbindlich)

Gilt für jedes Bash-Script dieser Basis und ihrer Projekte. Referenzimplementierung: templates/bash/. Die Scripts in bin/ sind nach diesem Standard gebaut und dienen als Beispiele.

1. Bausteine – drei Dateien, mehr nicht

<scriptdir>/
├── mein_script.sh          # Präambel (= Hilfe) + Bootstrap + Funktionen + main
├── _functions.sh           # gemeinsame Basis – Kopie aus templates/bash/, NICHT lokal ändern
├── _functions.local.sh     # optional: projektspezifische Funktionen (lädt _functions.sh automatisch)
├── .env                    # optional: Einstellungen (nie im Git)
└── .env.example            # Pflicht, wenn .env genutzt wird: gleiche Schlüssel, Platzhalter

Mehrere Scripts in einem Verzeichnis teilen sich _functions.sh und .env. Das frühere Modell (_global_functions.sh, _project_functions.sh, _project_settings.sh) entfällt: Settings → .env, Projektfunktionen → _functions.local.sh.

2. Aufbau eines Scripts

#!/usr/bin/env bash
#-------------------------------------------------------------------------------
## @file     backup_db.sh
## @brief    Sichert die Datenbank nach $DIR_BACKUP
## @author   <Name aus ai/context/responsible.md>
## @owner    <Name/Rolle aus ai/context/responsible.md>
## @assist   KI-unterstützt (<Modell>), geprüft von <author>
## @version  1.0.0 (07.10.2026)
##
## @usage    backup_db.sh [Optionen] <datenbank>
## @options
## @OPTIONS@
## @env      .env neben dem Script (Vorlage: .env.example)
## @exit     0 = ok · 1 = Fehler · 2 = Aufruffehler
#-------------------------------------------------------------------------------
set -Eeuo pipefail

SCRIPT_PATH="$(readlink -f -- "${BASH_SOURCE[0]}")"   # Bootstrap – unverändert übernehmen
SCRIPT_DIR="${SCRIPT_PATH%/*}"
SCRIPT_NAME="${SCRIPT_PATH##*/}"
source "${SCRIPT_DIR}/_functions.sh" || { echo "FEHLER: ${SCRIPT_DIR}/_functions.sh fehlt" >&2; exit 1; }

B_OPTS+=( "k|keep|value:TAGE|14|Sicherungen so lange behalten" )
b_init "$@"
set -- "${ARGS[@]}"

## @brief   Hauptablauf
## @param   $1  Datenbankname
## @return  0 ok, 1 Fehler
main() { … }

main "$@"

Präambel = Hilfe = Doku

• Der Header zwischen den ersten beiden #------Linien ist gleichzeitig die Hilfe (-h): b_usage gibt alle ##-Zeilen ohne ## aus.
• ## @OPTIONS@ wird durch die Optionsliste aus B_OPTS ersetzt → Hilfe und Optionen können nicht auseinanderlaufen.
• ## ist der Doku-Marker (wie /** bei javadoc). bin/bashdoc.sh script.sh erzeugt daraus Markdown. Normale Kommentare mit #.
• Header-Pflichtfelder: rules/headers.md.

3. Pfadsicherheit

Variable	Inhalt
SCRIPT_PATH	absoluter, aufgelöster Pfad des Scripts (Symlinks aufgelöst)
SCRIPT_DIR	Verzeichnis des Scripts – Basis für .env, _functions.sh, relative Pfade aus .env
SCRIPT_NAME	Dateiname des Scripts
B_CALL_DIR	$PWD beim Aufruf – Basis für relative Pfade von der Kommandozeile
B_LIB_DIR	Verzeichnis von _functions.sh
B_TMP_DIR	Temp-Verzeichnis nach b_tmpdir, wird beim Exit gelöscht

• Nie cd als Voraussetzung, nie relative Pfade ohne Basis. Helfer: b_abspath <pfad> [basis] (Default-Basis SCRIPT_DIR).
• Faustregel: Pfade aus .env/Defaults → relativ zu SCRIPT_DIR; Pfade, die der Benutzer tippt → relativ zu B_CALL_DIR.

4. Optionen (B_OPTS)

Format je Eintrag: "kurz|lang|typ[:META]|default|Beschreibung" – typ = flag (0/1) oder value.

Quelle	Wo	Hinweis
Standard (-h -d -q -n -l)	_functions.sh (B_OPTS_STD)	immer da
Script-eigen	im Script vor b_init: B_OPTS+=(…)	Regelfall
Verzeichnisweit	.env: B_OPTS+=(…)	gilt für alle Scripts des Verzeichnisses

• Ergebnis: Variable OPTION_<LANG> (Großbuchstaben, - → _): --dry-run → OPTION_DRY_RUN, --keep 7 → OPTION_KEEP=7.
• Unterstützt: -d, -dn (gebündelt), -l datei, -ldatei, --logfile datei, --logfile=datei, --debug=0, -- (Ende der Optionen). Positionsargumente landen in ARGS (auch zwischen Optionen).
• Unbekannte Option / fehlender Wert → Meldung, Hinweis auf --help, Exit 2.
• Immer += verwenden, nie B_OPTS=(…) (würde Einträge aus .env/_functions.local.sh löschen). Kein | in Default/Text.

Vorrang (und Gültigkeit von Umgebungsvariablen)

Default < .env < Umgebung < Kommandozeile

• Exportierte B_*/OPTION_*-Variablen aus der Umgebung werden vor dem Laden von .env gesichert und danach wiederhergestellt (B_LOG_LEVEL=debug ./script.sh gewinnt gegen .env). Nicht exportierte Shell-Variablen des Aufrufers sieht das Script ohnehin nicht.
• Für eigene Projektwerte in .env dasselbe Verhalten per VAR="${VAR:-default}".
• .env wird nicht automatisch exportiert. Werte, die Kindprozesse brauchen, explizit exportieren (Geheimnisse möglichst nicht).
• Wirkung der Standardoptionen: -d → B_LOG_LEVEL=debug, -q → B_LOG_CONSOLE=0, -l → B_LOG_FILE, -n → brun führt nichts aus.

5. Ausgabe & Logging – nie echo

Funktion	Level	Ziel Konsole	Zweck
becho "…"	info	stdout, ohne Präfix	Ersatz für echo
bdebug "…"	debug	stderr, [DEBUG]	Details, nur bei -d
bwarn "…"	warn	stderr, [WARN]	Auffälliges, Lauf geht weiter
berror "…"	error	stderr, [FEHLER]	Fehler melden (Funktion entscheidet über return)
bdie "…" [rc]	error	stderr	melden + beenden (rc 2 = Aufruffehler mit Hilfe-Hinweis)
blog <level> "…"	–	–	Basis aller obigen

Steuerung (.env, Umgebung oder Option):

Variable	Default	Bedeutung
B_LOG_LEVEL	info	Mindestlevel Konsole (debug/info/warn/error)
B_LOG_CONSOLE	1	Konsole an/aus
B_LOG_FILE	leer	Logdatei; leer = keine
B_LOG_FILE_LEVEL	= B_LOG_LEVEL	eigenes Mindestlevel für die Datei
B_LOG_COLOR	auto	Farben nur auf Terminal

Logdatei-Format: JJJJ-MM-TT hh:mm:ss LEVEL script.sh[PID] Text. Ausnahme vom echo-Verbot: echte Daten-Ausgabe für Pipes (printf '%s\n' "$ergebnis") – Meldungen gehen nie auf stdout außer über becho.

6. Fehler, Return-Codes, Aufräumen

• set -Eeuo pipefail ist Pflicht. b_init setzt Traps: EXIT (Aufräumen), ERR (meldet Befehl, Funktion, Zeile), INT/TERM (Exit 130/143 → EXIT-Trap).
• Return-Code-Prinzip: Jede Funktion endet mit return 0 (ok), 1 (Fehler) oder 2 (falscher Aufruf); dokumentiert unter @return. Fehler meldet die Funktion selbst (berror) und gibt den Code zurück – der Aufrufer entscheidet (if f; then, f || return 1).
• Ergebnisse über stdout (x="$(f)") oder globale Variablen mit Präfix – nie über Exit-Codes > 2.
• Aufräumen: Script definiert optional cleanup() { … } – wird vom EXIT-Trap mit dem Exit-Code aufgerufen, auch bei Fehler/Abbruch. Temporäres immer über b_tmpdir ($B_TMP_DIR), wird automatisch entfernt.

7. Funktionsdoku („briefly!“)

## @brief   Was die Funktion tut – ein Satz
## @param   $1  Bedeutung
## @param   $@  restliche Argumente
## @return  0 ok, 1 Fehler; Ausgabe auf stdout (falls zutreffend)
name() {

• Direkt über der Funktion, keine Leerzeile dazwischen. Interne Helfer mit _ beginnen (bashdoc.sh blendet sie ohne -p aus).
• local für alle Variablen in Funktionen.

8. Weitere Helfer aus _functions.sh

Funktion	Zweck
brun cmd args…	ausführen bzw. bei -n nur anzeigen (kein eval, Argumente als Array)
b_require prog…	prüft, ob Programme vorhanden sind
b_require_vars VAR…	prüft, ob Variablen gesetzt sind
b_tmpdir	legt $B_TMP_DIR an
b_abspath pfad [basis]	absoluter Pfad
b_usage	Hilfe ausgeben

9. Stil

• Bash ≥ 4.4. Shebang #!/usr/bin/env bash. 2 Leerzeichen Einrückung.
• Immer quoten ("$var", "${arr[@]}"), [[ ]] statt [ ], $(…) statt Backticks, printf statt echo -e.
• Dateinamen: Kleinbuchstaben, _ als Trenner, Endung .sh; Hilfsdateien mit _-Präfix.
• Variablen: Konstanten/Globale GROSS, lokale klein; Präfix B_/_B_/OPTION_ ist für _functions.sh reserviert.
• Prüfen vor Abgabe: bash -n, shellcheck -x, -h, -n, ein echter Lauf (lokal, rules/testing.md).

10. Neues Script in 4 Schritten

1. cp ai/common/templates/bash/{script_template.sh,_functions.sh,.env.example} <ziel>/ (_functions.sh nur, wenn noch nicht vorhanden).
2. Umbenennen, Header ausfüllen (Verantwortliche aus responsible.md), B_OPTS anpassen.
3. Funktionen mit Kurz-Doku + main schreiben.
4. Testen (§ 9), ggf. bin/bashdoc.sh für die Projektdoku.

Änderungsprotokoll

• 07.10.2026 – angelegt; Stack auf .env + _functions.sh (+ optional _functions.local.sh) reduziert.