Git Notes: Gits coolste und unbeliebteste Funktion (2022)

 (tylercipriani.com)
3 Punkte von GN⁺ 2025-06-23 | 1 Kommentare | Auf WhatsApp teilen
  • Git notes sind ein leistungsstarkes Werkzeug, um Metadaten an Commits und andere Objekte anzuhängen
  • Diese Funktion ermöglicht es, ergänzende Informationen zu speichern, wenn Commit-Messages nicht geändert werden können
  • Sie kann genutzt werden, um verschiedene Informationen wie Code-Review-Verlauf oder Testergebnisse zu speichern
  • Sogar ein verteiltes Code-Review-System lässt sich damit umsetzen, doch Bedienbarkeit und Bekanntheit sind gering
  • Wegen unzureichender Unterstützung, etwa durch die Deaktivierung auf GitHub, ist die alltägliche Nutzung gering

Was sind Git notes

  • Git notes sind eine Funktion in Git, mit der sich an beliebige von Git verfolgte Objekte (Commit, Blob, Tree) Metadaten anhängen lassen
  • Normalerweise kann eine einmal aufgezeichnete Commit-Message nicht geändert werden, aber mit git notes lassen sich neue Informationen hinzufügen, ohne den Commit-Inhalt zu verändern
  • Zum Beispiel lassen sich einem Commit wie folgt notes hinzufügen
    • git notes add -m 'Acked-by: <이메일>'
  • notes werden in git log zusammen mit einem separaten Abschnitt angezeigt

Praktische Einsatzfälle

  • Auch das Git-Projekt selbst nutzt git notes, um Commits mit Diskussions-Threads in der Mailingliste zu verknüpfen
  • Konkrete Beispiele für den Einsatz von notes sind unter anderem
    • Zeiterfassung pro Commit oder Branch
    • Speichern von Logs zu Code-Reviews und Testergebnissen
    • Entwurf eines vollständig verteilten Code-Review-Systems

Speichern von Code-Reviews und Testergebnissen

  • Immer mehr Code-Schmieden oder Review-Systeme unterstützen es, Code-Review-Metadaten offline, also direkt in Git selbst, zu speichern
  • Das reviewnotes-Plugin von Gerrit zeigt in git log zusammen mit notes an, wer das Review durchgeführt und welche Tests ausgeführt wurden
    • Nutzer können so lokal den Verlauf der Code-Prüfung einsehen, ohne extra einen Browser zu öffnen

Verteiltes Code-Review-System

  • Mit git-appraise, das bei Google entwickelt wurde, gibt es ein Beispiel dafür, wie sich mit git notes verteiltes Code-Review realisieren lässt
  • git-appraise zeichnet den gesamten Ablauf in git notes auf, darunter Code-Review-Anfragen, Kommentare zu Änderungen und Merges nach dem Review, und funktioniert unabhängig von Online-Code-Hosting-Diensten
  • Die gesamte Zusammenarbeit ist lokal möglich, und sogar eine Weboberfläche wird bereitgestellt

Geringe Bedienbarkeit und Bekanntheit

  • Git notes werden kaum genutzt, weil die Oberfläche umständlich ist und die Funktion für normale Nutzer nicht intuitiv wirkt
  • GitHub zeigt Commit-notes seit 2014 nicht mehr an, wodurch die Nutzungsmöglichkeiten weiter zurückgingen
  • Die Verwaltung von notes für Commits lässt sich per Git-Konfiguration etwas einfacher machen, aber um notes an Blob- oder Tree-Objekte anzuhängen, braucht es zusätzliches Verständnis von Gits interner Struktur (plumbing)
  • Dadurch bleiben git notes weiterhin eine Nischenfunktion mit sehr geringer Bekanntheit

Unabhängigkeit von offenen Forges

  • Git selbst kann verteilte Versionsverwaltung und Code-Review unterstützen, doch viel zusätzlicher Mehrwert wie Review-Verläufe ist stark an Hosting-Dienste wie GitHub gebunden
  • Mit der Git-notes-Funktion eröffnet sich ein Weg, nicht nur die Entwicklung des Codes, sondern auch die gesamte Projekthistorie verteilt zu speichern und zu verbreiten
  • Das hat große Bedeutung für ein vollständig verteiltes Entwicklungsökosystem und die Bewahrung von Projektgeschichte

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-06-23
Hacker-News-Kommentare

  • Hinweis auf ein wenig bekanntes Feature namens Git-Trailer; Trailer ermöglichen es, beim Erstellen eines Commits Metadaten in Form von Schlüssel-Wert-Paaren einzufügen. Wird in Gerrit verwendet, um Change-Id anzuhängen. Passender Artikel

    • Hinweis auf eine ähnliche Funktion namens COMMENT in PostgreSQL; mit COMMENT kann Text zu Datenbankobjekten hinzugefügt werden. Es wird gehofft, dass PostgreSQL auch das Bearbeiten strukturierter Metadaten im Schlüssel-Wert-Format anbieten wird. Passende Dokumentation

    • Erfahrungsbericht zur Nutzung von git notes, um bei Open-Source-Upstream-Arbeit Commits zu markieren, für die Unit-Tests abgeschlossen waren; nützlich beim Aufräumen eines Branches mit git rebase -i. Trailer erscheinen inzwischen aber als die bessere Methode. Wenn Funktionen wie Change-Id direkt in Git enthalten wären, könnten Tools sie wohl besser verstehen. Commits über Commit-Messages zu unterscheiden ist auf subtile Weise fragil; Commit-IDs sind zwar gut für Eindeutigkeit, verlieren aber als Identifikator an Nutzen, wenn dieselbe Änderung auf einen anderen Commit verschoben wird. Korrektur: Trailer sind Teil des Commits und können Notes daher nicht vollständig ersetzen.

    • Kürzlich entdeckt, dass GitHub statt [skip ci] einen eigenen Trailer nutzt, vermutlich damit er sich leichter aus der Commit-Message herauslösen lässt. Unklar ist, warum GitHub nur den letzten Trailer verlangt; vermutet wird, dass das an der Regex-Verarbeitung liegt. Passende Dokumentation

    • Trailer-Funktion war bisher unbekannt; als Fan von Conventional Commits scheint sie für das Hinzufügen solcher Metadaten besser geeignet. Es wird gefragt, ob das manuelle Hinzufügen zur Commit-Message funktional identisch zur Verwendung des Flags --trailer ist.

    • Eigentlich möchte man so etwas mit einem Issue-Tracking-System verbinden, aber es in etwas wie Trailer unterzubringen ist ineffizient, weil es zu weit vom Issue-Tracker entfernt ist. Issue-Tracker laufen Trends hinterher und bekommen viele Funktionen spät. Die Regel, dass ein aus dem Ticketnamen abgeleiteter Branchname zwingend als PR-Titel verwendet werden muss, ist lästig. Stattdessen möchte man Commits und Issues über andere Metadaten verknüpfen, um PR-Titel sinnvoller zu machen. Das ist kein Problem, das sich leicht ändern lässt, also eher etwas, worüber man im Internet schimpft.

  • Hinweis, dass Forgejo seit Version 10, die im Januar dieses Jahres veröffentlicht wurde, Trailer unterstützt. Release Notes Pull Request

  • Frage zur Wechselwirkung zwischen git notes und dem Umschreiben der Historie (amend, rebase usw.): Da Notes an Commit-/Tree-/Blob-IDs hängen, ist unklar, ob sie kopiert werden oder verschwinden, wenn ein Commit durch einen neuen ersetzt wird. Ebenso wird gefragt, was passiert, wenn man bei einem interaktiven Rebase mehrere Commits zusammenführt. Es wird angemerkt, dass die Vorstellung, Notes würden am „Inhalt“ einer Datei oder eines Verzeichnisses hängen, von den Erwartungen abweicht. Wenn man zum Beispiel dem Blob mit der Zeichenkette "Hello world!" eine Note anhängt, stellt sich die Frage, ob diese Note dann an allen Dateien mit demselben Inhalt hängt und ob bei einer Dateiänderung die Notes verloren gehen.

    • Beim git rebase usw. lässt sich das Kopieren von Notes standardmäßig so konfigurieren, dass es erfolgt; siehe die Option notes.rewrite in git-config(1).

  • Am aktuellen Arbeitsplatz werden git notes aktiv verwendet, um interne Code-Review-Historien zu verwalten, ohne Commit-Messages zu überladen oder für jede Änderung einen PR zu erstellen. Am Branch bleibt Kontext erhalten, etwa welchem Ticket ein Commit zugeordnet ist, welche Infrastruktur-Einschränkungen es gibt oder bei Fixes Links zu Incident-Threads. Wenn diese Informationen im Repo gespeichert sind, lässt sich leichter nachvollziehen, warum sich eine einzelne Zeile geändert hat, ohne Slack oder Jira durchsuchen zu müssen. In größerem Maßstab kann das den Bedarf an Platform-UI deutlich reduzieren. Die Ansicht ist, dass Reproduzierbarkeit nicht nur für Builds, sondern auch für die „Absicht“ nötig ist.

    • Frage, ob solche Informationen nicht besser in die Commit-Message gehören oder ob damit auch Verknüpfungen in die Zukunft gemeint sind, etwa „dieser Commit hat Bug #123 verursacht“.

  • git notes sind nur dann wirklich nützlich, wenn nach dem Commit zusätzliche Informationen gebraucht werden. Beispiele wie Acked-By oder Links zu Mailinglisten-Diskussionen sind Informationen, die man zum Commit-Zeitpunkt schon kennt und daher direkt in die Commit-Message schreiben kann. Der eigentliche Vorteil von git notes liegt eher darin, später zusätzliche Erklärungen an etwa zurückgenommene Commits anzuhängen.

    • Häufig behauptet eine Commit-Message stolz, einen Bug behoben zu haben, obwohl das in Wirklichkeit nicht der Fall war. Dadurch entstehen Folgefehler, und Kolleg:innen ignorieren oft die ursprüngliche Absicht und gehen oberflächlich darüber hinweg. Nach Erfahrungen mit verärgerten Kund:innen und wiederkehrenden Bugs entsteht das Gefühl, bei „bug fix“ vorsichtiger sein zu müssen. Manchmal behebt man auch mehrere Bugs auf einmal, oder ein Refactor eröffnet nebenbei Möglichkeiten für Performance-Verbesserungen oder neue Features.

    • Acked-By, Reviews und Diskussionen setzen sich oft erst nach dem Commit fort; zum Zeitpunkt des Commits kann man sie noch nicht kennen. Fälle eines commit revert sind dagegen eher nützlich in der Commit-Message aufgehoben, weil blame die letzte Änderung zeigt und so ohnehin eine natürliche Nachverfolgung für zurückgenommene Commits bietet.

    • Diskussionen dauern oft auch nach dem Commit weiter an.

  • Interessanter Punkt, dass es sich lohnen könnte, die Notes-Funktion zu erforschen, um Code-Agenten zusätzlichen Kontext zu geben.

  • Das ist kein Wissensproblem, sondern ein UI-Problem; wenn die GitHub-Oberfläche Notes gut anzeigen würde, würden sie sofort viel häufiger genutzt.

    • Es wäre wünschenswert, wenn GitHub Notes unterstützen würde.

  • Git hat viele „coolste und unbeliebte Features“ wie bisect, pickaxe, reflog, range-diff, archive und annotierte Tags, aber die meisten Leute benutzen es kaum, weil sie es eher wie Google Drive betrachten.

    • git notes wirken doppelt, weil nichttechnischer Kontext wie Features oder Roadmaps ohnehin in separaten Projektmanagement-Tools wie Jira verfolgt wird. Der Unix-Philosophie folgend sollte jedes Werkzeug bei seiner Aufgabe bleiben.

    • pickaxe war eine völlig neue Funktion und kam unerwartet; ein Hinweis darauf, nicht zu selbstsicher zu werden.

    • Solche dekorativen Funktionen sind in der Praxis oft gar nicht so nützlich; ein Blick darauf als Nebentechniken rund um das Eigentliche.

  • Meinung, dass git notes kein wirklich „cooles“ unloved feature sind, sondern nur in sehr speziellen, eng begrenzten Situationen nützlich waren. Dass alle wirklich nötigen Informationen in der Commit-Message stehen und von anderen Systemen wie JIRA referenziert werden können, sei eher ein Vorteil. Systeme wie JIRA dienen als Kommunikationskanal zu Business-Analyst:innen oder Support-Mitarbeitenden, und es ist nachvollziehbar, dass Nicht-Entwickler:innen keinen Zugriff auf Repo und Code haben. Wenn mehrere Services oder Repos gleichzeitig betroffen sind, sind Feature-Referenzen über Notes ohnehin unrealistisch; es braucht eine Anbindung an externe Systeme.

    • Es wird darauf hingewiesen, dass es ineffizient ist, wenn Business-Analyst:innen keinen Zugriff auf Code oder Repo haben, weil man sonst immer wieder Fragen beantworten muss, die sich oft schon durch das Ansehen einer einzigen Codezeile klären ließen. Es gibt zwar Analyst:innen mit technischem Verständnis, aber kulturell lässt sich das nur schwer ändern.

  • Über die Manpage wurde etwa 2020 zum ersten Mal von Notes erfahren. Standardmäßig gelten Notes nur für das lokale Repo, daher gibt es keine praktische Nutzungserfahrung. Damit Teams sie gemeinsam nutzen können, muss das Pushing/Fetchen separat konfiguriert und bewusst beschlossen werden, und das eigene Team hat sich dagegen entschieden.