# Git-Hook

## Was es ist

Ein Git-Hook ist ein Programm, das Git selbst an einem festgelegten Punkt seiner Arbeit startet: bevor ein Commit aufgezeichnet wird, nachdem eine Commit-Nachricht geschrieben wurde, bevor ein Push den Rechner verlässt oder wenn ein Server einen empfängt. Jeder Hook ist eine Datei ohne Endung, die nach diesem Zeitpunkt benannt ist, etwa `pre-commit`, `commit-msg` oder `pre-push`. Standardmäßig sucht Git im Verzeichnis `.git/hooks` des Repositorys danach; mit `core.hooksPath` lässt sich ein anderer Ort angeben. Die Datei muss ausführbar sein, denn Git ignoriert sie ohne gesetztes Ausführungsbit. Sie kann aber in jeder Sprache geschrieben sein, die der Rechner ausführen kann.

Clientseitige Hooks laufen im eigenen Klon eines Entwicklers und werden bei Vorgängen wie Commits und Merges ausgelöst. Serverseitige Hooks laufen auf dem Rechner, der Pushes empfängt, etwa einer Forge, und werden ausgelöst, wenn gepushte Commits eintreffen.

Sein Rückgabestatus macht aus einem Hook zur Benachrichtigung einen Hook zum Durchsetzen von Regeln. Der Hook `pre-commit` erhält keine Argumente. Ein Rückgabestatus ungleich null bricht den Commit ab. `commit-msg` erhält den Pfad einer Datei mit der vorgeschlagenen Nachricht und kann sie ablehnen oder bearbeiten. `pre-push` erhält den Namen und die Adresse des Remotes als Argumente sowie über die Standardeingabe eine Zeile je Referenz. Ein Status ungleich null stoppt den Push, bevor etwas gesendet wird. Auf dem Server läuft `pre-receive` einmal je Push. Er liest für jede Referenz den alten Objektnamen, den neuen Objektnamen und den Referenznamen. Endet er mit einem Status ungleich null, wird keine der Referenzen aktualisiert. Nach dem Ereignis laufende Hooks wie `post-commit` dienen der Benachrichtigung und können das Ergebnis nicht mehr ändern.

Wenn `git init` ein Repository anlegt, füllt es das Hook-Verzeichnis mit Beispielskripten, deren Namen auf `.sample` enden. Git führt ein solches Skript erst aus, nachdem diese Endung beim Umbenennen entfernt wurde.

## Warum es wichtig ist

Ein Hook macht aus einer Prüfung, an die jemand denken muss, eine Prüfung, die von selbst und zum günstigsten Zeitpunkt stattfindet. Ein Formatierer oder ein Secret-Scanner, der beim Erstellen des Commits läuft, findet ein Problem, solange der Autor die Änderung noch im Kopf hat. Es fällt dann nicht erst Tage später im Review oder nach dem Teilen der Arbeit in einem CI-Lauf auf.

Hooks machen eine Regel außerdem zu einer Eigenschaft des Repositorys und lösen sie von der Person, die gerade committet. Eine Konvention in einem Leitfaden für Mitwirkende gilt nur, solange die Leute ihn lesen. Dieselbe Konvention in einem Hook vom Typ `commit-msg` gilt für jeden Commit.

Die beiden Gruppen unterscheiden sich darin, wie viel sie versprechen können. Das Buch Pro Git weist darauf hin, dass beim Klonen eines Repositorys dessen clientseitige Hooks nicht kopiert werden, und empfiehlt, Regeln auf der Serverseite durchzusetzen. Ein serverseitiger Hook wie `pre-receive` gilt für jeden Push von jedem Mitwirkenden, unabhängig von dessen lokaler Installation. Der Preis ist Zeit: Ein Hook läuft bei jedem Commit oder jedem Push. Eine Prüfung, die Commits verlangsamt, lädt zum Umgehen ein.

## Wie es in der Praxis aussieht

Das Repository dieser Website installiert seine Hooks über das Framework pre-commit. Die Konfiguration steht in `.pre-commit-config.yaml`; die Hooks installiert `task setup`, das `pre-commit install --install-hooks` ausführt. Die Datei installiert drei Git-Hooks. In der pre-commit-Phase laufen Prettier, markdownlint, stylelint, yamllint, codespell, Ruffs Lint- und Formatprüfungen, ein gitleaks-Scan nach Geheimnissen, eine Emoji-Prüfung und eine Prüfung des sprachlichen Tons. In der commit-msg-Phase erzwingt ein Skript eine konventionelle Form der Nachrichten ohne Emojis. In der pre-push-Phase läuft die gesamte verbindliche Qualitätsprüfung, `task check`. Sie dauert Minuten statt Sekunden. Der Kommentar zu diesem Hook akzeptiert den Preis, weil ein Push selten ist. Der Dateikopf verbietet das Umgehen der Hooks mit `--no-verify`, und der Kommentar bleibt dabei: Ein Push, der nicht warten kann, ist nicht bereit.

Ein Hook für Commit-Nachrichten setzt außerdem für vier Repositorys einen gemeinsamen Standard für die Historie durch: ein konventionelles Präfix mit Geltungsbereich, eine Betreffzeile unter einer festgelegten Länge, keine Emojis und keine Attribution-Trailer. Der Hook lehnt alles ab, was davon abweicht, und zwar in jedem Repository, das Arbeit enthält. Der Standard gehört damit zum Repository und nicht zur jeweils committenden Person.

Ein serverseitiger Hook für die unternehmenseigene Forge wurde erprobt, bevor ihn ein echter Push erreichte. Ein solcher Hook läuft in einem Bare-Repository ohne Arbeitsbaum, in einer von der Forge gesetzten Umgebung, und liest gepushte Referenzen über die Standardeingabe. Ihn von Hand auf einem Laptop auszuführen, beweist deshalb wenig. Die Erprobung legt ein Bare-Repository an, installiert den Hook, klont, committet und pusht und prüft sowohl den Annahme- als auch den Ablehnungspfad. Dabei wurden zwei Fehler gefunden, die beim Lesen der Datei nicht erkennbar waren. Beide werden unten beschrieben.

In einem Projekt stellte sich heraus, dass Commit-Hook und Qualitätsprüfung unterschiedliche Prüfungen ausführten, obwohl ein Dokument behauptete, der Hook führe die Qualitätsprüfung aus. Ein Test ermittelt nun für beide die tatsächlich aufgerufenen Prüfungen und schlägt fehl, wenn die Mengen auseinanderfallen. Die fünf Prüfungen, die nur in der Qualitätsprüfung gelaufen waren, lasen die Lebenslauftexte. Der Code war somit bei jedem Commit geschützt, die Texte nur, wenn jemand daran dachte.

Ein clientseitiger Hook braucht überhaupt kein Framework. Dieser hier, gespeichert als `.git/hooks/commit-msg` und ausführbar gemacht, lehnt einen Commit ab, dessen Betreff nicht mit einem konventionellen Typ beginnt:

```sh
#!/bin/sh
# git passes the path of the proposed commit message as $1
pattern='^(feat|fix|docs|chore)(\([a-z0-9-]+\))?: .+'
if head -n 1 "$1" | grep -Eq "$pattern"; then
    exit 0
fi
echo "commit-msg: start the subject with a type, as in 'fix(nav): ...'" >&2
exit 1
```

## Wo es schiefgeht
* Ein frischer Klon kommt ohne Hooks an. Jeder Klon muss sie installieren. Hier erledigt das `task setup`. Ein Kommentar in der `Taskfile.yml` dieser Website beschreibt die unauffällige Form des Fehlers: Ohne `pre-commit` auf dem Rechner installiert `task setup` nichts, sämtliche Hooks bleiben stillschweigend aus, und das Ergebnis sieht genauso aus wie ein Repository, das alle Prüfungen besteht.
* `--no-verify` geht geradewegs an ihnen vorbei. `git commit --no-verify` umgeht `pre-commit` und `commit-msg`, `git push --no-verify` umgeht `pre-push`, und `core.hooksPath` auf `/dev/null` zu setzen, schaltet alle Hooks zugleich ab. Eine Regel, die gelten muss, gehört auch in einen serverseitigen Hook.
* Gits Umgebung folgt dem Hook in andere Repositorys. Git exportiert Variablen wie `GIT_DIR`, damit Git-Befehle in einem Hook das richtige Repository finden. githooks(5) empfiehlt, sie zu entfernen, wenn ein Hook in einem anderen arbeitet. Genau das trat bei der Forge-Erprobung auf: Die Qualitätsprüfung checkte die gepushte Revision aus und führte darin die Tests aus. Diese erbten Gits Verweis auf das Bare-Repository, und neunzehn von ihnen schlugen bei korrektem Code fehl.
* Die Standardeingabe transportiert die Randfälle. Der andere Fehler der Erprobung lag in einer Ausweichlösung, die mangels einer verwendbaren Referenz einen von Git nicht auflösbaren Platzhalter einsetzte. Weil der Wert über die Standardeingabe ankommt, erschien der Fehler erst viel später als scheinbar unzusammenhängende Fehlermeldung. Die Seite hält außerdem fest, dass die Forge erzwungene Aktualisierungen und gelöschte Branches sehen wird, die die Erprobung nicht nachstellt. Laut githooks(5) erreicht eine gelöschte Referenz `pre-push` als `(delete)` mit einem ausschließlich aus Nullen bestehenden Objektnamen.
* Ein langsamer Hook wird umgangen. Die fünf Textprüfungen in den Commit-Hook aufzunehmen, erforderte, zwei davon für das Zeitbudget eines pre-commit-Hooks schnell genug zu machen. Die Seite sagt deutlich, dass die Laufzeit mit dem Inhalt wächst und irgendwann der Punkt erreicht ist, an dem ein langsamer Hook umgangen wird.
* Das Format passt, die Bedeutung bleibt ungeprüft. Wie die Seite über die vier Repositorys sagt: Das Format wird geprüft, der Inhalt nicht. Eine formal passende Betreffzeile, die nichts beschreibt, besteht daher genauso wie eine, die die Änderung erklärt.

## Weiterführende Lektüre
* githooks-Dokumentation — sämtliche von Git unterstützten Hooks, ihre Ausführungszeitpunkte, ihre Eingaben und die Entscheidungen, die ihr Rückgabestatus trifft.
* Pro Git: Git-Hooks — clientseitige und serverseitige Hooks, ihre Installation und warum sie beim Klonen zurückbleiben.
* Pro Git: Beispiel einer durch Git erzwungenen Richtlinie — ein serverseitiger Hook vom Typ `update`, der ein Nachrichtenformat und Zugriffsregeln durchsetzt, mit clientseitigen Hooks, die vor dem Push warnen.
* git config — die Einstellung `core.hooksPath`, um Hooks aus `.git/hooks` zu verlagern oder alle abzuschalten.
* git commit — die Option `--no-verify` und die zwei Hooks, die sie umgeht.
* git push — der Hook `pre-push` und die Option `--no-verify`, die ihn überspringt.

=> /de/portfolio/held-4-repositories-to-one-history-standard/ für vier Repositorys einen gemeinsamen Standard für die Historie
=> /de/portfolio/rehearsed-the-forge-ci-hook-found-2-defects/ Ein serverseitiger Hook für die unternehmenseigene Forge wurde erprobt
=> /de/portfolio/found-the-hooks-and-the-gate-disagreeing/ Commit-Hook und Qualitätsprüfung unterschiedliche Prüfungen ausführten
=> https://git-scm.com/docs/githooks githooks-Dokumentation
=> https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks Pro Git: Git-Hooks
=> https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy Pro Git: Beispiel einer durch Git erzwungenen Richtlinie
=> https://git-scm.com/docs/git-config git config
=> https://git-scm.com/docs/git-commit git commit
=> https://git-scm.com/docs/git-push git push

=> https://engineer.company/de/glossary/git-hook/ Diese Seite im Web
