Git Best Practices

Macht früh Commits

Macht euren ersten Commit nachdem ihr die initiale Installation fertiggestellt habt und noch bevor ihr erste Änderungen vornehmt.

Verwendet ihr ein Cookiecutter-Template, committet unmittelbar nach den folgenden Schritten:

$ pipenv run cookiecutter https://github.com/veit/cookiecutter-namespace-template.git
full_name [Veit Schiele]:
email [veit@cusy.io]:
github_username [veit]:
project_name [cusy.example]:
…

Anschließend könnt ihr die initialen Änderungen in ein neu erstelltes, leeres Repository auf GitHub einchecken:

$ cd cusy.example
$ git init
$ git add *
$ git commit -m 'Initial commit'
$ git remote add origin ssh://git@github.com:veit/cusy.example.git
$ git push -u origin main

Schließt unerwünschte Dateien aus

Temporäre Dateien, Jupyter Checkpoints und builds haben in einem Repository nichts zu suchen. Passwörter erst recht nicht. Die .gitignore-Datei enthält eine Liste von Dateipfaden, die git nicht hinzufügt, außer ihr wünscht das explizit.

Eine Vorlage mit .gitignore-Einträgen für Python-Projekte findet ihr im Repository dotfiles. Auf der Website gitignore.io könnt ihr euch .gitignore-Vorlagen für euer Projekt generieren lassen. Auch die .gitignore-Datei gehört in das Repository eingecheckt:

$ git add .gitignore
$ git commit -m 'Add .gitignore file'

Falls ihr versehentlich schon entsprechende Dateien in euer Git-Repository eingecheckt habt, beispielsweise einen .ipynb_checkpoints-Ordner, könnt ihr diese wieder entfernen mit:

$ git rm -r .ipynb_checkpoints/

Schreibt eine README-Datei

Auch eine README-Datei sollte in jedem Repository vorhanden sein, in der das Deployment und der grundsätzliche Aufbau des Codes beschrieben wird.

Macht oft Commits

Nach jeder abgeschlossenen Aufgabe und Teilaufgabe sollte ein Commit erfolgen. Auch nicht abgeschlossene Aufgaben können auf git gesichert werden. Als Faustregel gilt: Committe mindestens einmal pro Tag, nämlich kurz vor Feierabend. In Stoßzeiten kann es auch vorkommen, dass ihr alle 10 Minuten committet.

Häufige Commits erleichtern euch:

  • das Eingrenzen von Fehlern

  • das Verständnis für den Code

  • die zukünftige Wartung und Pflege.

Falls ihr doch einmal mehrere Änderungen an einer Datei durchgeführt habt, könnt ihr diese auch später noch in mehrere Commits aufteilen mit:

$ git add -p my-changed-file.py

Ändert die veröffentlichte Historie nicht

Auch wenn ihr zu einem späteren Zeitpunkt herausfindet, dass ein Commit, der mit git push bereits veröffentlicht wurde, einen oder mehrere Fehler enthält, so solltet ihr dennoch niemals versuchen, diesen Commit ungeschehen zu machen. Vielmehr solltet ihr durch weitere Commits den oder die aufgetretenen Fehler zu beheben.

Warnung

Die große Ausnahme zu dieser Regel sind Workflows mit git-rebase wie in Feature-Branches.

Wählt einen Git-Workflow

Wählt einen Workflow, der am besten zu eurem Projekt passt. Projekte sind keineswegs identisch und ein Workflow, der zu einem Projekt passt, muss nicht zwingend auch in einem anderen Projekt passen. Auch kann sich initial ein anderer Workflow empfehlen als im weiteren Fortschritt des Projekts.

Schreibt aussagekräftige Commit-Nachrichten

Aufschlussreiche und beschreibende Commit-Nachrichten erleichtern euch die Arbeit im Team ungemein. Sie ermöglichen anderen und euch selbst, eure Änderungen zu verstehen. Auch sind sie zu einem späteren Zeitpunkt hilfreich um nachvollziehen zu können, welches Ziel mit dem Code erreicht werden sollte.

Üblicherweise sollten kurze, 50–72 Zeichen lange Nachrichten angegeben werden, die in einer Zeile ausgegeben werden, z.B. (zum Beispiel) mit git log --oneline.

Mit git blame könnt ihr euch auch später noch für jede Zeile angeben lassen, in welcher Revision und von welchem Autor sie kam. Weitere Informationen hierzu findet ihr in der Git-Dokumentation: git-blame.

Bemerkung

Gitmojis

Wenn ihr Gitmojis in euren Commit-Nachrichten verwendet, könnt ihr später leicht die Absicht des Commits erkennen.

Bemerkung

GitLab

GitLab interpretiert bestimmte Commit-Nachrichten auch als Links, z.B.:

$ git commit -m "Expand section on meaningful commit messages (#21: Add
multi-line commit messages and close group/project#22)"

  • zu Issues: #NUMBER

    • auch in anderen Projekten: GROUP/PROJECT#NUMBER

  • zu Merge Requests: !NUMBER

  • zu Snippets:$NUMBER

Dabei sollte es zu jedem Commit mindestens ein Ticket geben, das ausführlichere Hinweise zu den Änderungen geben sollte. Alternativ könnt ihr auch mehrzeilige Commit-Nachrichten schreiben, die diese Informationen enthalten, z.B. + mit:

$ git commit -m 'Expand section on meaningful commit messages' -m 'Fix the serious problem'

Oder, wenn ihr nur git commit eingebt, öffnet sich euer Editor, z.B. mit folgendem Text:

# Bitte geben Sie eine Commit-Beschreibung für Ihre Änderungen ein. Zeilen,
# die mit '#' beginnen, werden ignoriert, und eine leere Beschreibung
# bricht den Commit ab.
#
# Auf Branch main

Git erwartet, dass ihr eure Commit-Nachricht am Anfang der Datei einfügt. Nachdem ihr die Bearbeitung der Datei abgeschlossen habt, liest Git ihren Inhalt und fährt fort. Es bereinigt die Datei, indem es mit # kommentierte Zeilen und nachfolgende Leerzeilen entfernt. Wenn die Nachricht nach dem Aufräumen leer ist, bricht Git den Commit ab – das ist praktisch, wenn ihr merkt, dass ihr etwas vergessen habt. Andernfalls wird der Commit mit dem verbleibenden Inhalt erstellt. GitLab verwendet # jedoch als Präfix für die Nummer eines Items. Diese doppelte Bedeutung von # kann zu einer Verwechslung führen, wenn ihr eine Commit-Nachricht schreibt, die sich auf ein Item bezieht:

Expand section on meaningful commit messages

#21: Add multi-line commit messages

# Bitte geben Sie eine Commit-Beschreibung für Ihre Änderungen ein. Zeilen,
# die mit '#' beginnen, werden ignoriert, und eine leere Beschreibung
# bricht den Commit ab.
#
# Auf Branch main
# Ihr Branch ist auf demselben Stand wie 'origin/main'.
#
# Zum Commit vorgemerkte Änderungen:
#       geändert:       productive/git/best-practices.rst
#

Üblicherweise entfernt Git die Zeile, die mit #21 beginnt, so dass die Nachricht wie folgt aussieht:

Expand section on meaningful commit messages

Vermeidet dieses Missgeschick, indem ihr einen alternativen Bereinigungsmodus namens Scissors verwendet. Ihr könnt ihn global aktivieren mit:

$ git config --global commit.cleanup scissors

Dann beginnt Git jede neue Commit-Nachricht mit der Scissors-Zeile:

# ------------------------ >8 ------------------------
# Ändern oder entfernen Sie nicht die obige Zeile.
# Alles unterhalb von ihr wird ignoriert.
#
# Auf Branch main
# Ihr Branch ist auf demselben Stand wie 'origin/main'.
#
# ...
#

Co-Autoren angeben

Wenn ihr mit einem Teammitglied an einem Commit arbeiten, ist es gut, dessen Beitrag mit dem co-authored-by-Trailer anzuerkennen. Trailer sind zusätzliche Metadaten am Ende der Commit-Nachricht, die eine KEY: VALUE-Syntax verwenden und wiederholt werden kann, um mehrere Werte aufzulisten:

Expand section on meaningful commit messages

#21: Add multi-line commit messages

co-authored-by: Kristian Rother <kristian.rother@cusy.io>
co-authored-by: Frank Hofmann <frank.hofmann@cusy.io>

GitLab analysiert die co-authored-by-Zeilen, um alle Avatare des Commits anzuzeigen und auch die Profilstatistiken der Co-Autoren zu aktualisieren usw.

Wartet euer Repository regelmäßig

Folgende Wartungsarbeiten solltet ihr regelmäßig durchführen:

Validiert das Repo

Der Befehl git fsck prüft, ob alle Objekte in der internen Datenstruktur von Git noch miteinander verknüpft sind.

Komprimiert das Repo

Spart Speicherplatz mit den Befehlen git gc bzw. git gc --aggressive.

Siehe auch

Bereinigt Remote Tracking Branches

Nicht genutzte Zweige auf einem entfernten Server lassen sich mit git remote update --prune löschen. Noch besser ist, wenn ihr die Standardeinstellung so ändert, dass entfernt gelöschte Zweige auch bei git fetch und git pull bei euch lokal gelöscht werden. Dies erreicht ihr mit:

$ git config --global fetch.prune true

Überprüft vergessene Arbeiten

Mit git stash list seht ihr eine List von gespeicherten stashes. Diese könnt ihr mit git stash drop entfernen.

Überprüft eure Repositories auf unerwünschte Dateien

Mit Gitleaks könnt ihr eure Repositories regelmäßig auf ungewollt gespeicherte Zugangsdaten überprüfen.

Ihr könnt Gitleaks auch automatisch als GitLab-Action ausführen. Hierzu müsst ihr die Secret-Detection.gitlab-ci.yml-Vorlage z.B. in eine Stufe namens secrets-detection in eurer .gitlab-ci.yml-Datei einbinden:

include:
- template: Security/Secret-Detection.gitlab-ci.yml

Die Vorlage erstellt Secret Detection-Aufträge in eurer CI/CD-Pipeline und durchsucht den Quellcode eures Projekts nach Secrets. Die Ergebnisse werden als Secret Detection Report Artefakt gespeichert, den ihr später herunterladen und analysieren könnt.

Siehe auch

Mit Entfernen einer Datei aus der Historie könnt ihr unerwünschte Dateien oder Zugangsdaten aus eurer Git-Historie entfernen.