Dateien aus Git heraushalten

In einem echten Projekt entstehen Dateien, die auf deinen Rechner gehören, aber nicht in seinen Verlauf. Ein Umgebungsverzeichnis lässt sich neu aufbauen, ein Cache wird automatisch erzeugt, und eine lokale Einstellungsdatei kann Werte enthalten, die nicht mit dem Projekt weitergegeben werden sollten. Im vorbereiteten Wettervorhersageprojekt liegen alle drei Arten neben nützlichen Quelldateien bereit.

Diese Lektion verwendet nur Beispieleinstellungen. API_TOKEN=demo-only-not-a-secret kann sich nirgendwo authentifizieren. Wenn echte Zugangsdaten bereits in einen Commit gelangt sind, reicht es nicht, sie aus der neuesten Momentaufnahme zu entfernen: Die Zugangsdaten müssen ersetzt werden, und das Bereinigen des alten Verlaufs ist eine eigene Aufgabe. Dieses Kapitel verhindert den Fehler, bevor er passiert.

Nachsehen, was Git gleich aufzeichnen wird

Mit git status siehst du bereits den Branch und alle Pfade mit ausstehenden Änderungen. Führe den Befehl aus, bevor du etwas änderst:

git status

Der Bericht zeigt local.env unter Changes to be committed. Die Datei liegt bereits in der Staging-Area. Der Index verfolgt sie also für den nächsten Commit, obwohl sie noch in keinem Commit enthalten ist. Außerdem zeigt der Bericht Dateien unter build/, __pycache__/ und .venv/ als nicht verfolgt an. Das sind erzeugte Ausgabedateien, ein Python-Cache und eine lokale Umgebung. Nichts davon gehört in den Projektverlauf.

Die bereits committete Datei examples/local.env ist etwas anderes. Sie ist ein unbedenkliches Beispiel, das jemand anderes kopieren kann. Deshalb darf die Regel für die Einstellungsdatei im Wurzelverzeichnis dieses Beispiel im Unterverzeichnis nicht ebenfalls verbergen.

Beschreiben, welche Dateien nicht dazugehören

Eine Datei namens .gitignore hält Projektpfade fest, die Git normalerweise nicht verfolgen soll. Die Datei selbst gehört ins Repository, damit alle, die das Projekt erhalten, denselben Schutz bekommen. Ignorierregeln ändern, was Git für einen zukünftigen Commit anbietet; sie löschen keinen Pfad, der bereits in einem Commit enthalten ist.

Öffne die neue Datei mit dem Terminaleditor aus Kapitel 2. nano -w öffnet nano, ohne bei einem schmalen Terminal feste Zeilenumbrüche einzufügen:

nano -w .gitignore

Gib diese vier Zeilen ein:

/local.env
build/
__pycache__/
.venv/

Die erste Regel ist ein verankertes Muster. Der führende / verankert local.env am Wurzelverzeichnis des Repositorys. Dadurch schützt es die lokale Datei, ohne auch examples/local.env zu ignorieren.

Die anderen Regeln sind Verzeichnismuster. Ein abschließender / kennzeichnet den Namen als Verzeichnis und ignoriert die Dateien darunter. build/ schützt erzeugte Build-Dateien. Weil __pycache__/ und .venv/ keinen führenden Schrägstrich haben, wird ein Verzeichnis mit einem dieser Namen überall im Projekt ignoriert.

Speichere mit Ctrl-O, bestätige .gitignore mit Enter und verlasse den Editor mit Ctrl-X.

Führe git status erneut aus. Die erzeugten Verzeichnisse tauchen nicht mehr in der Liste der nicht verfolgten Dateien auf, aber local.env liegt noch immer in der Staging-Area:

git status

Dieses Ergebnis ist beabsichtigt. Ignorierregeln setzen den Index nicht außer Kraft. Git hat local.env bereits vorgemerkt. Du musst deshalb den Indexeintrag entfernen und dabei die Arbeitsdatei behalten.

Die Kopie im Index entfernen und die Datei behalten

git rm entfernt einen Pfad normalerweise sowohl aus dem Git-Index als auch aus dem Arbeitsbaum. Die Option --cached beschränkt das Entfernen auf den Index, also die vorbereitete nächste Momentaufnahme von Git. In git rm --cached local.env benennt das letzte Argument den einen indizierten Pfad, den Git nicht länger verfolgen soll. Die Datei auf dem Datenträger bleibt erhalten.

Führe den Befehl aus und frage dann erneut den Status ab:

git rm --cached local.env
git status

local.env verschwindet aus dem Bericht, weil die Datei jetzt nicht mehr verfolgt wird und ihre Ignorierregel greift. Ihre Beispielinhalte liegen weiterhin auf dem Datenträger.

Git fragen, ob die Regeln passen

git check-ignore prüft Pfade gegen die Ignorierregeln des Repositorys. Gib nach dem Befehl einen oder mehrere Pfade an. Er gibt die ignorierten Pfade aus. Für einen Pfad, auf den keine Regel zutrifft, gibt er nichts aus.

Prüfe jede geschützte Art:

git check-ignore local.env build/preview.txt __pycache__/forecast.cpython-313.pyc .venv/bin/python

Alle vier Pfade sollten ausgegeben werden. Der Befehl prüft das Verhalten, statt dich aus der Schreibweise des Musters darauf schließen zu lassen. Das ist besonders nützlich, wenn eine Ignorierregel länger oder weniger offensichtlich ist als diese.

Den Schutz committen, nicht die privaten Dateien

git add .gitignore nimmt nur die Ignorierdatei in die Staging-Area auf. Das folgende git status dient deiner Kontrolle: Es sollte .gitignore als bereit für den Commit anzeigen und keinen der geschützten Pfade. Anschließend zeichnet git commit diese eine zusammengehörige Änderung auf. Die Option -m übergibt die Betreffzeile in Anführungszeichen, ohne einen Editor zu öffnen.

git add .gitignore
git status
git commit -m "Keep local project files out of Git"
git status

Der abschließende Status sollte einen sauberen Arbeitsbaum melden. Die lokalen und erzeugten Dateien existieren weiterhin, aber ignorierte Dateien machen den Arbeitsbaum nicht unsauber. Vor allem ist keine von ihnen in einen Commit gelangt.

Eine Gruppe von Dateinamen erfassen

In einem anderen Projekt muss vielleicht jede Datei mit der Endung .env privat bleiben, nicht nur eine Datei im Wurzelverzeichnis. In einem Ignoriermuster steht * für eine beliebige Zeichenfolge innerhalb eines Namens. Das Muster *.env passt deshalb auf local.env und testing.env; ohne Schrägstrich passt es auch auf solche Namen in Unterverzeichnissen. Es passt nicht auf environment.txt.

Behalte in dieser Übung /local.env bei: Das unbedenkliche examples/local.env ist hier absichtlich erlaubt. Wähle für das andere Projekt der Abschlussaufgabe, in dem jede .env-Datei privat bleiben soll, die umfassendere Regel *.env. Das Muster richtet sich nach den Anforderungen des Projekts.

Vergleiche vor dem Weitergehen settings/testing.env und settings/environment.txt. Welche Datei würde *.env ignorieren? Der erste Name endet auf .env und passt daher; der zweite nicht. Verwende git check-ignore mit repräsentativen Namen, wenn du die Regeln deines eigenen Projekts prüfst.

Du hast aus einer wiederkehrenden Aufräumentscheidung ein Verhalten des Projekts gemacht. Die nächste Lektion wendet die andere Hälfte dieser Gewohnheit an: Prüfe eine zusammengehörige Änderung, bevor du ihrer Momentaufnahme eine nützliche Betreffzeile gibst.