roselletabuena/git-atomic-commit

Atomare Commits

Ein atomarer Commit enthält genau eine logische Änderung. Der Nutzen besteht nicht in Ordnung um ihrer selbst willen – es sind drei konkrete Fähigkeiten, die das Team verliert, wenn Commits vermischt werden:

• Review: Ein Reviewer kann eine einzige Idee im Kopf behalten und beurteilen.
• Revert: Eine fehlerhafte Änderung kann rückgängig gemacht werden, ohne gute Änderungen mitzunehmen.
• Bisect: git bisect kann den Commit identifizieren, der einen Fehler eingeführt hat – das funktioniert nur, wenn jeder Commit eine Änderung ist und jeder Commit baut.

Der letzte Punkt wird am häufigsten übersehen. Atomar bedeutet nicht „so klein wie möglich“ – es bedeutet „eine vollständige Änderung“. Ein Commit, der eine Funktion von der Aufrufstelle trennt, die sie benötigt, ist zwar kleiner, aber nicht atomar, weil er den Baum kaputt macht.

Der Workflow

1. Bestandsaufnahme vor dem Stagen

Verstehe den gesamten Baum, bevor du entscheidest, wie du ihn aufteilst:

git status --porcelain      # jeder Pfad, einschließlich ungetrackter
git diff                    # ungestagte Änderungen
git diff --cached           # bereits gestagte Änderungen
git log --oneline -15       # wo HEAD ist und der lokale Stil

Widerstehe git add -A und git commit -a als ersten Schritt. Sie verwandeln einen gemischten Baum in einen gemischten Commit, und das Aufteilen danach ist strikt mehr Arbeit als das Aufteilen vorher. Prüfe auch auf Änderungen, die gar nicht committed werden sollten – Build-Ausgaben, .env-Dateien, Debug-Ausgaben, eine vergessene Editor-Konfiguration.

2. Änderungen in logische Einheiten gruppieren

Der zuverlässigste Test ist sprachlich: Formuliere den Commit-Betreff, und wenn er ein „und“ benötigt, um korrekt zu sein, hast du mehr als einen Commit. „Login-Weiterleitung korrigiert und Lodash aktualisiert“ sind zwei. Die Frage eines Reviewers ist der zweite Test: Müsste er Änderung X verstehen, um Änderung Y zu beurteilen? Wenn nicht, sind die Änderungen unabhängig und gehören getrennt.

Trennen:

Getrennt halten	Warum
Formatierung / Leerzeichen vs. Logik	Eine Neuformatierung vergräbt die drei eigentlichen Zeilen in 400 Rauschangeilen. Dies ist die mit Abstand wertvollste Trennung.
Umbenennungen vs. Verhaltensänderungen	Gleicher Grund – eine Umbenennung betrifft alles und versteckt die eine Zeile, die zählt.
Abhängigkeitsupdates vs. Code	Jedes benötigt seine eigene Revert-Historie.
Unabhängige Fehlerkorrekturen	Unabhängige Reverts, unabhängige Bisects.
Refactoring vs. die darauf aufbauende Funktion	Ermöglicht einem Reviewer zu bestätigen, dass das Refactoring verhaltenserhaltend ist.

Zusammenhalten:

In einem Commit halten	Warum
Eine Änderung und ihre Tests	Sie sind eine logische Einheit; Tests für nicht ausgelieferten Code oder Code ohne Tests sind jeweils nur eine halbe Änderung.
Eine Umbenennung und alle ihre Aufrufstellen	Das Trennen hinterlässt einen kaputten Baum – das Gegenteil von atomar.
Eine Signaturänderung und ihre Aufrufer	Gleicher Grund.
Eine Änderung und die dazugehörige Dokumentation/Changelog	Sie beschreiben dieselbe Entscheidung und sollten zusammen rückgängig gemacht werden.

3. Commits so ordnen, dass jeder baut

Die Reihenfolge ist wichtig, weil jeder Commit den Baum funktionsfähig hinterlassen sollte. Setze Grundlagen vor die Dinge, die sie nutzen: füge den Helfer vor dem Code hinzu, der ihn aufruft, mache das Refactoring vor der darauf aufbauenden Funktion, lege das Schema vor der Abfrage an. Wenn zwei Gruppen voneinander abhängig sind, ist das ein Zeichen, dass sie eigentlich ein Commit sind.

4. Jede Gruppe stagen

Verwende die am wenigsten invasive Technik, die funktioniert. Eskaliere nur, wenn die einfachere die Aufteilung nicht abbilden kann:

Stufe 1 – ganze Dateien stagen. Dies deckt die große Mehrheit der realen Aufteilungen ab, weil logische Änderungen normalerweise in verschiedenen Dateien leben:

git add src/auth.py tests/test_auth.py
git commit -m "..."

Stufe 2 – ganze Dateien auslagern, wenn etwas im Baum sonst leicht versehentlich committed werden könnte:

git stash push -- requirements.txt    # parken
# ... den Rest committen ...
git stash pop                         # zurückholen

Stufe 3 – Änderungen innerhalb einer einzigen Datei aufteilen. Nur nötig, wenn eine Datei tatsächlich zwei logische Änderungen enthält. Die Mechanik ist knifflig und leicht subtil falsch zu machen, lies daher vor dem Versuch references/splitting-one-file.md.

git add -p funktioniert nicht in nicht-interaktiven Umgebungen und scheitert still. Es zeigt den ersten Hunk an, erreicht EOF auf stdin, staged nichts und beendet mit 0. Ein Erfolgs-Rückgabecode bedeutet hier, dass nichts passiert ist. Gleiches gilt für git add -i, git commit -p und git checkout -p. Da der Fehler wie ein Erfolg aussieht, ist der Schaden normalerweise ein Commit, der leer ist oder die beabsichtigte Änderung vermissen lässt – verwende stattdessen die Techniken aus der Referenzdatei und überprüfe den Index mit git diff --cached vor dem Commit.

5. Jede Nachricht im eigenen Stil des Repositories schreiben

Passe dich der umgebenden Historie an, anstatt eine Konvention zu importieren. Ein feat:-Präfix in einem Log mit einfachen Prosa-Betreffen ist Rauschen und lässt die Historie wie zwei Projekte aussehen. Lies zuerst den lokalen Stil:

git log --no-merges --format='%s' -n 30               # Betreff-Stil
git log --no-merges -n 10 --format='%n---%n%s%n%b'    # ob Bodies verwendet werden

Achte auf: ein type:- oder type(scope):-Präfix (Conventional Commits), ein Ticket-Präfix wie [PROJ-123], Großschreibung, Imperativ vs. Vergangenheit („Hinzufügen“ vs. „Hinzugefügt“), typische Betreff-Länge und ob Bodies normal sind oder Betreffe allein stehen. Übernimm, was du findest. Conventional Commits ist eine gute Voreinstellung nur, wenn das Log es bereits verwendet oder das Repository noch keine Historie hat und der Benutzer keine Präferenz hat.

Was auch immer der lokale Stil ist, der Betreff sollte sagen, was sich geändert hat, und der Body – wenn die Historie Bodies verwendet – sollte sagen, warum, da der Diff bereits das Was zeigt. Wenn das Repository eine CONTRIBUTING.md oder einen Commit-msg-Hook hat, überschreiben diese die Inferenz aus dem Log.

Eine Konvention zu befolgen bedeutet nie, die Daten zu erfinden, die sie trägt. Wenn der lokale Stil eine Ticket- oder Issue-Referenz einbettet – [PROJ-123], Fixes #456 – und dir wurde keine echte Kennung gegeben, rate keine und setze die Nummerierung aus dem Log nicht fort. Ein plausibel aussehendes [PROJ-124] ist schlimmer als gar kein Präfix: Es ist permanent, es liest sich wie echte Rückverfolgbarkeit, und es zeigt wahrscheinlich auf ein fremdes, nicht zusammenhängendes Ticket. Lass die Referenz weg, passe den Rest des Stils an und sage in deiner Antwort, dass die ID fehlt, damit der Benutzer sie nachreichen kann – der Commit ist noch nicht gepusht und lässt sich leicht ändern. Frage nach der Nummer, wenn der Benutzer erreichbar ist.

6. Vor der Rückgabe überprüfen

git log --oneline -n <anzahl>     # die Form dessen, was du gebaut hast
git status --porcelain           # was, falls überhaupt, übrig ist

Bestätige, dass jeder Commit nur seine eigene Änderung enthält (git show --stat <sha>), und dass nichts unter den Tisch gefallen ist. Wenn Änderungen bewusst nicht committed bleiben, sage das explizit – ein Baum, den der Benutzer für sauber hielt, es aber nicht ist, ist das schlechteste Ergebnis hier, weil er es später entdeckt und nicht weiß, ob es beabsichtigt war.

Leitplanken

• Gestalte das Wie des Commitings, nicht das Ob. Wenn der Benutzer keinen Commit gewünscht hat, macht dieser Skill es nicht angemessen, einen zu erstellen, und er impliziert nie das Pushen.
• Verwerfe niemals Arbeit, um eine Aufteilung zu erleichtern. git checkout -- <datei>, git reset --hard und git stash drop zerstören nicht committed Arbeit, die noch kein Commit hält – sie ist unwiederbringlich. Wenn eine Technik eine dieser Aktionen benötigt, sichere den Inhalt zuerst und bestätige, dass die Sicherung existiert, bevor du sie ausführst.
• Schreibe keine veröffentlichte Historie um, um sie aufzuräumen. Das Aufteilen bereits gepushter Commits bedeutet einen Force-Push, der die Historie anderer umschreibt, die sie möglicherweise gezogen haben; frage zuerst.
• Zersplittere nicht übermäßig, um gründlich zu wirken. Drei Commits, die jeweils den Build brechen, sind schlechter als einer, der funktioniert. Bei Unsicherheit bevorzuge die Gruppierung, die jeden Commit funktionsfähig hält.
• Wenn der Baum nur eine logische Änderung enthält, committe sie als eine. Nicht jeder Baum muss aufgeteilt werden, und das zu sagen ist ein gutes Ergebnis.