Git-Stilrichtlinien

Dies sind Git-Stilrichtlinien, inspiriert von How to Get Your Change Into the Linux Kernel, den git man pages sowie unterschiedlichen anderen, populären Vorgehensweisen.

Übersetzungen sind für folgende Sprachen verfügbar:

• Chinesisch (vereinfacht)
• Chinesisch (traditionell)
• Französisch
• Griechisch
• Japanisch
• Koreanisch
• Portugisisch
• Spanisch
• Thailändisch
• Türkisch
• Ukrainisch

Wenn du zu diesem Projekt beitragen willst, fühle dich willkommen! Erstelle einen Fork des Projekts und öffne einen Pull-Request!

Inhaltsverzeichnis

1. Branches
2. Commits
3. Nachrichten
4. Merging
5. Weiteres

Branches

• Wähle kurze und beschreibende Namen:

  # gut
  $ git checkout -b oauth-migration
  
  # schlecht – zu ungenau
  $ git checkout -b login_fix

• Identifikatoren von korrespondierenden Tickets in externen Services (z. B. GitHub-Issues) sind auch gute Kandidaten für Branch-Namen, zum Beispiel:

  # GitHub Issue #15
  $ git checkout -b issue-15

• Nutze Bindestriche, um Wörter zu trennen!

• Wenn mehrere Leute am selben Feature arbeiten, kann es hilfreich sein, persönliche Feature-Branches sowie einen team-weiten Feature-Branch zu haben. Befolge folgende Namenskonvention:

  $ git checkout -b feature-a/master # Team-weiter Branch
  $ git checkout -b feature-a/maria  # Marias persönlicher Branch
  $ git checkout -b feature-a/nick   # Nicks persönlicher Branch

  Mergen der persönlichen Branches mit dem Team-weiten Branch erfolgt hier nach Belieben (vergleiche "Merging"). Beizeiten wird der Team-weite Branch dann in den "master"-Branch gemerged.

• Lösche deinen Branch nach dem Mergen aus dem Upstream-Repository, sofern dem nichts entgegen steht!

  Tipp: Benutze den folgenden Befehl vom "master"-Branch aus, um gemergede Branches anzuzeigen:

  $ git branch --merged | grep -v "\*"

Commits

• Jedes Commit sollte eine einzelne, zusammenhängende Änderung repräsentieren. Fasse nicht mehrere unabhängige Änderungen in einem Commit zusammen! Wenn beispielsweise eine Änderung einen Bug behebt und Performanceverbesserungen vornimmt, sollte sie auf zwei separate Commits aufgeteilt werden.

  *Tipp: Nutze git add -p, um interaktiv einzelne Abschnitte modifizierter Dateien zu stagen!

• Spalte nicht eine einzelne, zusammenhängende Änderung in mehrere Commits auf! So sollten beispielsweise die Implementation eines Features und die korrespondierenden Tests in einem Commit zusammengefasst sein.

• Committe früh und oft! Kleine, abgeschlossene Commits sind einfacher zu verstehen und leichter rückgängig zu machen, falls etwas schief geht.

• Commits sollten logisch geordnet sein. Wenn beispielsweise Commit X von Änderungen aus Commit Y abhängt, dann sollte Commit Y vor Commit X kommen.

Notiz: Beim unabhängigen Arbeiten an einem lokalen Branch, der noch nicht gepusht wurde, ist es unproblematisch, Commits als temporäre Schnappschüsse der eigenen Arbeit zu benutzen. Hier gilt es jedoch, die Commits vor dem Pushen entsprechend zu pflegen, sodass sie den Regeln entsprechen.

Nachrichten

• Benutze den Editor, nicht das Terminal, um Commit-Nachrichten zu schreiben:

  # gut
  $ git commit
  
  # schlecht
  $ git commit -m "Quick fix"

  Commits vom Terminal zu erstellen, befürwortet die Einstellung, die ganze Commit-Nachricht in eine einzelne Zeile zu bekommen. Dies führt typischerweise zu uninformativen, mehrdeutigen Commit-Nachrichten.

• Die Zusammenfassung (1. Zeile der Nachricht) sollte beschreibend aber knapp sein. Idealer Weise sollte sie nicht länger als 50 Zeichen sein. Sie sollte sich an Groß- und Kleinschreibung halten und im Imperativ, Präsens geschrieben sein. Sie sollte nicht mit einem Satzzeichen enden, weil sie effektiv der Titel der Commit-Nachricht ist:

  # gut – Imperativ, Präsens, großer Anfang, weniger als 50 Zeichen
  Mark huge records as obsolete when clearing hinting faults
  
  # schlecht
  fixed ActiveModel::Errors deprecation messages failing when AR was used outside of Rails.

• Nach der Zusammenfassung sollte eine Leerzeile kommen, der eine detailliertere Beschreibung folgt. Diese Beschreibung sollte bei 72 Zeichen umgebrochen werden und erklären, warum die Änderung notwendig war, wie das Problem gehandhabt wird, und welche Nebeneffekte auftreten könnten.

  Die Beschreibung sollte auch auf weitere Ressourcen hinweisen (z. B. durch einen Link zum Issue im Bugtracker):

  kurze (50 Zeichen max.) Zusammenfassung
  
  detaillierterer Text, wenn notwendig; umgebrochen bei spätestens 72
  Zeichen. In manchen Zusammenhängen werden die erste Zeile
  als Betreff einer E-Mail und die genauere Beschreibung als Inhalt
  benutzt. Hier ist die Leerzeile häufig besonders wichtig,
  solange nicht der Inhalt weg fällt.
  Programme wie "rebase" können fehlerhaft reagieren,
  wenn die Leerzeile fehlt.
  
  Weitere Paragraphen werden durch Leerzeilen getrennt.
  
  - Stichpunkte sind auch in Ordnung.
  
  - Es werden Bindestriche oder Sternchen,
    durch ein Leerzeichen separiert, benutzt.
    Zwischen einzelnen Stichpunkten folgt eine Leerzeile.
  
  Quelle http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
  

  Denke beim Schreiben einer Commit-Nachricht vor allem an die Frage, was du wissen wollen würdest, wenn du die Nachricht in einem Jahr lesen würdest!

• Wenn ein Commit A von einem Commit B abhängt, sollte diese Abhängigkeit in der Commit-Nachricht von Commit A festgehalten werden. Benutze die SHA1-Hashes, um Commits zu referenzieren!

  Wenn Commit A entsprechend einen Bug behebt, der durch Commit B hervorgerufen wurde, sollte dies genauso festgehalten werden.

• Wenn ein Commit mit einem Anderem gesquashed werden soll, benutze --squash und --fixup entsprechend, um die Intention offenzulegen:

  $ git commit --squash f387cab2

  (Tipp: Nutze --autosquash beim rebasen! Die markierten Commits werden dann automatisch gesquashed.)

Merging

• Schreibe nicht veröffentlichte Geschichte um! Die Geschichte eines Repositories ist für sich genommen wertvoll, und es ist wichtig, feststellen zu können, was tatsächlich passierte. Veränderungen der veröffentlichten Geschichte sind eine typische Problemquelle und stören alle Beteiligten an einem Projekt.

• Es gibt trotzdem Ausnahmen, bei denen es legitim ist, die Geschichte zu ändern:

  • Du arbeitest alleine an einem Branch und dieser wird nicht reviewed.

  • Du möchtest deinen Branch aufräumen (z. B.: Commits squashen) und/oder zum "master"-Branch rebasen, um später zu mergen.

  Ansonsten gilt „Ändere niemals die Geschichte des "master"-Branches!“ oder irgendeines speziellen Branches (z. B. von CI-Servern genutzt).

• Halte die Geschichte sauber und einfach! Direkt vor dem Mergen deines Branches:

  1. Stelle sicher, dass dein Branch den Stilrichtlinien entspricht und räume gegebenenfalls entsprechend auf (Squashen/Umsortieren von Commits, Umschreiben von Commit-Nachrichten, …)!

  2. Rebase deinen Branch auf den Branch, mit dem er gemerged werden soll:

  ```shell
  [my-branch] $ git fetch
  [my-branch] $ git rebase origin/master
  # then merge
  ```
  
  Dies führt zu einem Branch, der direkt ans Ende des "master"-Branches
  passt und damit zu einer sehr einfachen Geschichte.
  
  *(Notiz: Diese Strategie passt besser zu Projekten
    mit kurzzeitigen Branches. Ansonsten kann es besser sein,
    den "master"-Branch gelegentlich zu mergen, anstatt darauf zu rebasen.)*
  

• Wenn dein Branch mehr als ein Commit enthält, merge nicht mit fast-forward:

  # gut – stellt sicher, dass ein Merge-Commit erstellt wird
  $ git merge --no-ff my-branch
  
  # schlecht
  $ git merge my-branch

Weiteres

• Es gibt eine Reihe von Workflows mit jeweils unterschiedlichen Stärken und Schwächen. Ob ein Workflow eine gute Wahl ist, hängt ab vom Team, dem Projekt und eurem Vorgehen beim Entwickeln.

  Trotzdem ist es wichtig, sich wirklich auf einen Workflow festzulegen und diesem zu folgen.

• Sei konsistent! Dies betrifft den Workflow, aber gilt auch für Commit-Nachrichten, Branch-Namen und Tags. Ein konsistenter Stil im Repository sorgt dafür, dass es einfach ist, durch Lesen des Logs und von Commit-Nachrichten, herauszufinden, was vor sich geht.

• Teste vor dem Pushen! Veröffentliche keine unfertige Arbeit!

• Benutze annotierte Tags, um wichtige Releases oder wichtige Geschichtspunkte zu markieren! Bevorzuge leichtgewichtige Tags zum persönlichen Gebrauch, z. B. als Lesezeichen oder zukünftige Referenzen!

• Halte dein Repository sauber durch gelegentliches Ausführen von Wartungsarbeiten:

  • git-gc(1)
  • git-prune(1)
  • git-fsck(1)

Lizenz

Diese Arbeit ist lizenziert unter der Creative-Commons-Attribution-4.0-International-Lizenz.

Mitwirkende

Agis Anastasopoulos – @agisanast – http://agis.io ‧ Kontributoren