Pre-Commit-Hooks für übernommene Repositories: einfache Leitplanken

Warum übernommene Repos weiterbrechen

Ein übernommenes Repo ist Code, den du nicht selbst geformt hast. Die Regeln sind unklar, der Stil ist gemischt, und „auf meinem Rechner lief es“ taucht auf, weil niemand wirklich weiß, was das Repo erwartet.

Die Probleme beginnen klein und werden zu echten Ausfällen: eine Datei nutzt Tabs, eine andere Spaces; ein schneller Fix fügt eine Abhängigkeit hinzu, pinnt aber nicht die Version; eine Konfigurationsdatei wird von Hand bearbeitet und driftet weg von dem, was die Produktion braucht. Selbst einfache Änderungen werden riskant, weil das Repo voller versteckter Annahmen ist.

Sich nur auf CI-Checks zu verlassen ist meist zu spät. CI läuft, nachdem der Commit bereits geteilt ist, Reviews sind bereits im Gange und Leute haben womöglich schon den kaputten Zustand gezogen. Wenn CI fehlschlägt, verschwendet ihr Zeit mit erneuten Pipelines, Rebasen und Raten, welche Änderung das Problem ausgelöst hat. Mit der Zeit hören Reviewer auf, den Signalen zu vertrauen, weil Fehler „normal“ wirken.

Der eigentliche Schaden entsteht dadurch, wie sich kleine schlechte Commits aufsummieren:

• Eine winzige Formatierungsänderung erzeugt laute Diffs, sodass ein echter Bug durchrutscht.
• Ein Lint-Problem wird mit „kommt später“ abgetan und wird zur Regel.
• Ein Test wird lokal nicht ausgeführt, sodass ein kaputter Build alle blockiert.
• Ein Secret wird committed und löst eine hektische Rotation der Schlüssel aus.

Pre-Commit-Hooks helfen, weil sie die häufigsten Prüfungen an den frühestmöglichen Punkt verlegen: bevor eine Änderung ein geteiltes Problem wird. Sie schaffen außerdem eine konsistente Basis, ohne lange Debatten über „den richtigen Weg“.

Wenn es funktioniert, sieht es langweilig aus (im positiven Sinn): weniger kaputte Builds, kleinere Diffs und schnellere Merges, weil Reviews sich auf Logik statt auf Stil konzentrieren.

Was Pre-Commit-Leitplanken abfangen sollten

Übernommene Repos scheitern auf vorhersehbare Weise. Das Ziel ist nicht, jeden Commit zu blockieren. Es geht darum, die wenigen hochwirksamen Fehler zu stoppen, die Lärm erzeugen, Builds brechen oder Daten leaken.

Fang mit Formatierungsdrift an. Unformatierte Dateien erzeugen riesige Diffs, die echte Änderungen verbergen. Ein One-Line-Bugfix sollte nicht mit 400 Zeilen Whitespace-Churn kommen. Auto-Formatting beim Commit hält Reviews lesbar und Merges weniger schmerzhaft.

Fang dann Lint-Probleme ab, die auf echte Bugs hindeuten, nicht auf Stilfragen: undefinierte Variablen, ungenutzte Importe, verdächtige Vergleiche, fehlende awaits oder gefährliche Muster wie aus Strings zusammengesetzte SQL-Anweisungen. Wenn dein Linter hauptsächlich über Kommata meckert, lernen Leute, ihn zu ignorieren.

Secrets sind der große Punkt. Keys schleichen sich ein, wenn jemand eine .env kopiert, ein Token in eine Konfig einfügt oder ein Debug-Log mit Zugangsdaten hinzufügt. Ein Secret-Scan sollte den Commit blockieren, bevor er jemals ein Remote erreicht.

Und schließlich: schnelle Tests, die Sekunden kosten, nicht Minuten. Der beste Hook ist der, den Leute eingeschaltet lassen. Ein kleiner Smoke-Test, ein schneller Unit-Subset oder ein grundlegender Type-Check fängt offensichtliche Regressionen früh.

Ein praktisches Set von Dingen, die es wert sind, blockiert zu werden:

• Auto-Format-Änderungen (damit Diffs klein bleiben)
• Lint-Fehler mit hohem Signal (wahrscheinlich Bugs)
• Gefundene Secrets (Tokens, API-Keys, private Keys)
• Schnelle Tests oder Type-Checks (schnelles rot-grün Feedback)
• Sanity-Checks (gültiges JSON/YAML, Konsistenz von Lockfiles)

Wähle ein kleines Werkzeug-Set, das zum Repo passt

Beim Übernehmen eines Repos geht es nicht um „maximale Abdeckung“. Es geht um weniger kaputte Commits. Starte mit drei oder vier Checks, denen das Team vertraut, und füge nur hinzu, wenn das Team aufhört, gegen das Tool zu kämpfen.

Ein gutes Starter-Set:

• Ein Formatter (auto-fix, kein Streit)
• Ein Linter (fängt echte Fehler, nicht Stilfragen)
• Ein Secret-Scanner (verhindert das Leaken von Keys)
• Ein schneller Test oder Build-Check (Sekunden, keine Minuten)

Passe die Tools an die Sprache an, die du wirklich nutzt. Bei mehreren Sprachen halte die Checks auf die entsprechenden Ordner beschränkt, damit eine Seite die andere nicht ausbremst.

Geschwindigkeit ist wichtiger als Perfektion. Wenn ein Hook 30–60 Sekunden braucht, werden Leute ihn umgehen. Bevorzuge Werkzeuge, die vorhersehbar sind: gleiche Ausgabe auf jeder Maschine, wenige False Positives und klare Fixes.

Entscheide, was einen Commit blockiert und was nur warnt. Blocken sollte für Dinge reserviert sein, die fast immer falsch sind (Formatierung, offensichtliche Lint-Fehler, Secrets). Warnungen eignen sich besser für „vielleicht“-Regeln (Komplexitätsgrenzen, strenge Stilregeln), bis das Repo stabil ist.

In einem Monorepo hilft eine einfache Regel: führe nur aus, was sich geändert hat. Änderst du den API-Ordner, führe API-Lint und einen schnellen API-Test aus, nicht das ganze Repo.

Schritt-für-Schritt: Pre-Commit zu einem übernommenen Repo hinzufügen

Erstelle einen Baseline-Branch (oder Tag) vom aktuellen main-Branch. Führe dann die Checks einmal über das ganze Repo aus, um die Blast-Range zu sehen. Dieser erste Lauf soll nicht perfekt sein. Er zeigt, was bereits kaputt ist, was nur Stilrauschen ist und was am ersten Tag jeden blocken würde.

Wähle als Nächstes, wie Hooks laufen sollen.

• Ein Pre-Commit-Framework ist leichter, um es im Team zu teilen, und verhält sich auf den meisten Maschinen gleich.
• Native Git-Hooks sind simpel, aber sie sind lokal-only per Default, daher vergessen Leute sie oder installieren sie nie.

Für die meisten Teams funktioniert eine geteilte, im Repo konfigurierte Einrichtung am besten, weil die Konfiguration wie jeder andere Change reviewbar ist.

Halte die Konfiguration langweilig: eine Datei, klare Namen und nur die Checks, die du tatsächlich durchsetzen willst. Installiere Hooks lokal und bestätige, dass sie laufen, indem du eine winzige Änderung machst und committest.

Ein Rollout, das Drama vermeidet:

• Erstelle einen Baseline-Branch und führe alle Hooks einmal aus, um zu protokollieren, was fehlschlägt.
• Füge die Konfigurationsdatei zum Repo hinzu und halte die erste Menge an Hooks klein.
• Installiere Hooks und verifiziere, dass sie bei einem echten Commit laufen.
• Starte damit, nur auf geänderten Dateien zu laufen (oder im Warnmodus), dann wechsle zu blockierend.
• Füge einen neuen Hook nach dem anderen hinzu, damit Fehler leicht zu verstehen sind.

Graduelle Durchsetzung ist wichtig. Wenn dein erster Commit wegen 700 Formatierungsänderungen blockiert, umgehen Leute die Hooks. Behebe erst hochriskante Probleme (Secrets, offensichtliche Lint-Fehler), dann kümmere dich um Formatierung.

Formatierung hinzufügen, die Stil-Debatten beendet

Formatierung ist die einfachste Leitplanke und zahlt sich schnell aus. Wähle einen Formatter pro Sprache und behandle ihn als einzige Quelle der Wahrheit. Sobald das Repo einen konsistenten Stil hat, können Reviews sich auf Logik konzentrieren, nicht darauf, ob jemand Tabs oder andere Anführungszeichen benutzt hat.

Für Geschwindigkeit formatiere nur gestagte Dateien. Das hält Commits flott und vermeidet das „eine Zeile berührt und 2.000 Zeilen ändern sich“-Problem.

Eine gute Basis für Formatierung verhindert laute Diffs, die Zeit verschwenden:

• Normalisiere Zeilenenden (damit Windows und macOS nicht kämpfen)
• Entferne trailing whitespace
• Sorge dafür, dass Dateien mit einer Newline enden
• Halte die Dateikodierung konsistent (gewöhnlich UTF-8)

Sei vorsichtig mit generierten Dateien und Vendor-Ordnern. Meist willst du nicht, dass ein Formatter Build-Outputs, Lockfiles, die du nicht besitzt, oder kopierten Drittcode umschreibt. Schließe sie explizit aus, damit Formatierung vorhersehbar bleibt:

# Beispielidee (keine vollständige Konfiguration)
exclude: "^(dist|build|vendor|\.next|coverage)/"

Stimmt außerdem ab, wann Formattierung stattfindet. Wenn du „format on save“ im Editor nutzt, sollte Formatierung beim Commit damit übereinstimmen, nicht dagegen kämpfen. Eine einfache Regel funktioniert gut: format on save für den Alltagskomfort und Formatierung beim Commit erzwingen, damit das Repo sauber bleibt, auch wenn jemand einen anderen Editor nutzt.

Linting hinzufügen, das echte Probleme findet

Linting ist in übernommenen Repos am nützlichsten, wenn es echte Bugs verhindert und nicht Streit über Kommata auslöst. Mit Pre-Commit-Hooks ist das Ziel einfach: offensichtliche Fehler stoppen, bevor sie in einen Branch gelangen und Zeit in CI verschwenden.

Wähle einen Linter, der zu deiner Hauptsprache passt, und konfiguriere ihn so, dass Bug-Signale Priorität haben gegenüber persönlichen Stilfragen. Regeln, die sich schnell auszahlen, sind z. B.:

• Unbenutzte Variablen und Importe
• Fehlende Fehlerbehandlung (ungesehene Promises, ignorierte Rückgabewerte)
• Unsicherer String-Bau (häufige Quelle für Injection-Bugs)
• Verdächtige Vergleiche und unerreichbarer Code
• Copy-Paste-Fehler und duplizierte Logik

Wenn dein Repo typisiert ist, füge dort, wo es hilft, einen leichten Type-Check hinzu. Beginne nicht damit, die ganze Codebasis zu type-checken. Ziel die Teile, die in Produktion am häufigsten brechen (Auth, Payments, Data Access) und weite erst dann aus.

Legacy-Code ist der Grund, warum Linting in übernommenen Projekten fehlschlägt. Versuche nicht, die ganze Welt zu reparieren, nur um eine Leitplanke zu mergen. Nutze gezielte Ignor-Regeln oder beschränke Linting auf geänderte Dateien. Eine andere Option ist eine temporäre Baseline, sodass der Hook nur neue Verstöße blockiert und du alte Probleme nach und nach abarbeitest.

Mach die Ausgabe freundlich. Bevorzuge Konfigurationen, die eine kurze Erklärung und einen Vorschlag zur Behebung zeigen, und aktiviere Auto-Fix, wo es sicher ist.

Halte die Laufzeit vorhersehbar. Ein Hook, der manchmal 5 Sekunden und manchmal 2 Minuten braucht, wird deaktiviert. Ziel ist konsistente, schnelle Prüfungen auf gestagten Dateien; schwerere Analysen gehören in CI.

Secret-Scanning hinzufügen, bevor etwas das Remote erreicht

Übernommene Repos verbergen oft Secrets im Klartext. Ein schneller Secret-Scan in deinen Pre-Commit-Hooks fängt offensichtliche Leaks (API-Keys, Access Tokens, private Keys, OAuth-Client-Secrets) ab, bevor sie einen Laptop verlassen.

Nutze einen Scanner, der Muster erkennt und neue Leaks blockiert. Viele Teams lassen den Commit fehlschlagen, wenn ein neues Secret eingeführt wird, erlauben aber eine geprüfte Baseline bekannter Funde.

Mach die Regel einfach: blockiere Commits, die neue Secrets hinzufügen. Wenn der Hook anschlägt, entfernt der Entwickler das Secret oder markiert es als geprüften False Positive über einen kontrollierten Prozess (nicht indem der Hook deaktiviert wird).

Für Ausnahmen ist eine explizite Allowlist sinnvoll, die leicht reviewbar ist. Halte die Baseline in der Versionskontrolle und behandle Änderungen daran als bedeutend.

Secrets schleichen sich meist über einige vorhersehbare Wege ein:

• .env-Dateien und lokale Konfiguration
• Beispiel-Settings-Dateien
• Debug-Logs und Error-Dumps
• Test-Fixtures und aufgezeichnete HTTP-Responses
• Kopierte Snippets aus Vendor-Dashboards

Wenn du ein bereits committetes Secret findest, behandle es als kompromittiert, auch wenn das Repo privat ist:

• Key/Token rotieren oder widerrufen
• Entferne es aus dem Code und ersetze es durch eine Umgebungsvariable
• Prüfe die Git-Historie und säubere sie, falls nötig
• Suche nach Verwendungen (Logs, Deployments, CI)
• Füge eine Regression-Check hinzu, damit es nicht nochmal passiert

Schnelle Tests hinzufügen, die Entwickler:innen tatsächlich laufen lassen

Die einzigen Tests, die beim Commit helfen, sind die, die Leute nicht überspringen. Ziel ist ein kleines, zuverlässiges Set, das auf einem normalen Laptop unter 60 Sekunden fertig ist. Dauert es länger, umgehen Entwickler es und die Leitplanke wird zum Lärm.

Starte mit Smoke-Tests, die beweisen, dass das Repo noch buildet und die wichtigsten Pfade funktionieren. Gute Kandidaten sind Tests, die offensichtliche Brüche schnell entdecken, nicht vollständige Coverage.

Was in Pre-Commit laufen sollte

Halte es kurz und an Fehlern orientiert, die ihr wirklich gesehen habt:

• Build-Check (kompilieren, typecheck oder minimaler Bundle-Check)
• Datenbank-Migrations-Sanity (Schema validieren oder gegen eine wegwerfbare DB anwenden)
• Ein bis zwei API-Calls (Health-Endpoint, Kern-Create-Read-Flow)
• Auth-Smoketest (Login funktioniert, geschützte Route bleibt geschützt)
• Eine minimale Unit-Test-Subset, als „smoke“ oder „fast“ getaggt

Mach den Befehl auf jeder Maschine mit minimaler Einrichtung lauffähig. Bevorzuge einen einzigen Einstiegspunkt (z. B. make-Task oder package-Script), der mit klarer Ausgabe fehlschlägt. Vermeide Abhängigkeiten von speziellen Diensten, die nur auf dem Rechner einer Person laufen.

Wohin die schwereren Tests gehören

Wenn eine Suite Minuten braucht, verschiebe sie aus Pre-Commit:

• Pre-Commit: nur schnelle Smoke-Tests
• On push / PR: volle Unit- und Integrationstests
• Nightly: langsame End-to-End-Tests, Load-Checks, Dependency-Audits

Um Tests deterministisch zu halten, reduziere flakige Netzwerkabhängigkeiten. Stub externe APIs, friere Zeit ein, wo nötig, und nutze lokale Fixtures. Wenn ein Service getroffen werden muss, mach ihn optional und standardmäßig in Pre-Commit überspringbar.

Beispiel: Stabilisierung eines KI-generierten Prototype-Repos

Stell dir ein Repo vor, das als schneller Prototyp von einem KI-Coding-Tool entstanden ist. Es demonstriert gut, aber in Produktion bricht es immer wieder. Auth hängt, Ordnerstruktur ist chaotisch und jede Änderung birgt die Gefahr, ein neues Loch zu öffnen.

Hier glänzen Pre-Commit-Hooks: kleine Leitplanken stoppen die schlimmsten Fehler früh, ohne eine große Umstrukturierung zu erzwingen.

Ein einfacher Drei-Commit-Rollout hält das Vertrauen hoch:

• Erster Commit: Formatter und ein grundlegender Linter mit sicheren Defaults hinzufügen.
• Zweiter Commit: Secret-Scanning hinzufügen, eventuell committete .env-Dateien sorgfältig entfernen, durch Beispiel-Dateien ersetzen und geleakte Keys rotieren.
• Dritter Commit: Einen Smoke-Test hinzufügen, der den letzten Ausfall widerspiegelt (z. B. ein Auth-Flow, der eine gültige Session erzeugen muss).

Wenn du diese Änderungen einem nicht-technischen Gründer oder Kunden erklärst, konzentriere dich auf Ergebnisse:

• „Das verhindert, dass Passwörter und API-Keys versehentlich das Laptop verlassen.“
• „Das fängt offensichtliche Fehler ab, bevor sie Zeit in CI oder beim Deploy kosten.“
• „Dieser eine schnelle Test verhindert genau den Ausfall, für den ihr zuletzt zahlen musstet.“
• „Nichts davon verändert Features. Es macht künftige Änderungen nur sicherer."

Häufige Fallen und wie man sie vermeidet

Übernommene Repos haben bereits genug Reibung. Der schnellste Weg, Pre-Commit scheitern zu lassen, ist, es wie Strafe wirken zu lassen. Gute Leitplanken sind meist still und laut nur, wenn sie etwas fangen, das später Zeit kosten würde.

Hooks schnell und vorhersehbar halten

Die größte Falle ist, Hooks so strikt zu machen, dass niemand mehr committen kann. Dauert es länger als eine Minute, greifen Leute zum Bypass-Flag und hören auf, dem Setup zu vertrauen.

Praktische Regeln:

• Führe lokal nur schnelle Checks aus (format, lint, secrets, ein kleiner Smoke-Test).
• Lauf nicht die komplette Testsuite bei jedem Commit.
• Fixe nur gestagte Dateien. Das automatische Ändern ungestagter Dateien erzeugt überraschende Diffs.
• Starte mit Warnungen für laute Regeln, zieh dann nach, wenn das Repo sauberer ist.
• Mach die Ausgabe klar: eine Fehlermeldung sollte sagen, was als Nächstes zu tun ist.

Wenn Formatter oder Linter regelmäßig Dateien berühren, die nicht Teil des Commits sind, wechsle zu einem gestaged-only Modus oder nutze ein Tool, das das unterstützt, damit Hooks nie an der Arbeit in Arbeit entlang schreiben.

Bypassen zur bewussten Wahl machen

Eine andere Fehlerquelle ist, Leuten zu erlauben, Hook-Fehler ohne Plan zu ignorieren. Manchmal ist Bypassen gerechtfertigt (Hotfix, kaputtes Upstream-Tool, dringende Demo), aber es sollte eine wohlüberlegte Ausnahme sein.

Setze Erwartungen im Repo:

• Dokumentiere, wann Bypass erlaubt ist und welche Nacharbeit nötig ist.
• Wenn jemand bypassed, sollte CI trotzdem dieselbe Art von Problemen fangen.

Achte auf CI-Parität. Wenn Entwickler lokal eine Linter-Version nutzen und CI eine andere, entstehen „works on my machine“-Commits. Pinne Tool-Versionen und halte lokale Hooks mit CI synchron, damit Fehler konsistent sind.

Kurze Checkliste und nächste Schritte

Wenn du Pre-Commit-Hooks in ein übernommenes Repo einführst, halte den ersten Schritt klein und verlässlich. Du willst offensichtliche Probleme früh abfangen, ohne Commits wie Strafe wirken zu lassen.

Eine Basis, die du an einem Nachmittag einrichten kannst:

• Auto-Format beim Commit
• Lint nur für die Dateien, die du berührt hast (schnell, informationsstark)
• Scan auf Secrets (Keys, Tokens, private Keys, versehentliche .env-Commits)
• Einen schnellen Test-Command laufen lassen (Smoke-Test oder fokussierte Unit-Tests)
• Tool-Versionen pinnen

Rolle es gestaffelt aus, damit das Team nicht gegen die Änderung kämpft:

1. Basis: Hooks nur auf neue oder geänderte Dateien laufen lassen
2. Warnen: Hooks lokal Fehler anzeigen, aber CI noch nicht blockieren
3. Erzwingen: Commits blockieren und CI fehlschlagen lassen, wenn Hooks fehlschlagen

Nach einer Woche solltest du weniger „Formatting“-Commits sehen, weniger PR-Kommentare zum Stil, weniger CI-Fehler durch leicht abfangbare Probleme und schnellere Reviews, weil sich die Aufmerksamkeit auf Logik statt auf Lärm richtet.

Weißt du, wann aufzuhören ist. Wenn jeder Hook tiefere Probleme aufdeckt (flaky Tests, zufällig brechende Auth, leake Konfigurationen, verhedderte Module), werden Leitplanken die Basis nicht reparieren. Dann braucht es gezielte Reparaturarbeit: restrukturieren, Sicherheit härten und die Grundlage schaffen, auf der schnelle Tests tatsächlich etwas aussagen.

Wenn das Repo als KI-generierter Prototyp begann und in Produktion weiter Probleme macht, ist FixMyMess (fixmymess.ai) genau für solche Fälle gebaut: Codebasis diagnostizieren, Logik und Sicherheitsprobleme beheben und für Deployments vorbereiten. Ein kurzes Audit hilft auch zu entscheiden, welche Leitplanken zuerst sinnvoll sind, damit du das Team nicht ausbremst.