.gitignore

Überblick

In einer Arbeitskopie betrachtet Git jede Datei in einem von drei Zuständen: verfolgt (bereits im Repository oder gestaged), nicht verfolgt (neu und noch nicht gestaged) oder ignoriert (bewusst ausgeschlossen). Dieses Kapitel erklärt, wie man Git mithilfe einer .gitignore-Datei anweist, Dateien zu ignorieren: die Mustersyntax, wo Ignorierregeln gespeichert werden können (pro Verzeichnis, pro Repository und global) und wie man mit kniffligen Fällen umgeht — eine bereits committete Datei ignorieren, eine ignorierte Datei mit Zwang committen, ignorierte Dateien stashen und debuggen, warum eine Datei ignoriert wird.

Ignorierte Dateien sind diejenigen, bei denen Git explizit angewiesen wurde, sie zu überspringen. Sie werden niemals gestaged, niemals committet und erscheinen niemals unter git status als nicht verfolgte Einträge. Typische Kandidaten sind Dateien, die aus dem Quellcode generiert werden, anstatt von Hand verfasst zu werden:

• Zur Laufzeit erzeugte Dateien — Logs, Lock-Dateien (*.log, *.lock).
• Betriebssystem- und IDE-Metadaten — .DS_Store, Thumbs.db, .idea/, .vscode/.
• Kompilierte Ausgaben und Abhängigkeiten — *.o, *.class, node_modules/, dist/.
• Geheimnisse und lokale Konfiguration — .env, Credential-Dateien.

Die Faustregel lautet: Wenn eine Datei aus dem Repository-Quellcode neu generiert werden kann oder maschinenspezifisch ist, sollte sie ignoriert werden.

Git-Ignore-Muster

Ignorierregeln befinden sich in einer Klartextdatei namens .gitignore. Es gibt keinen git ignore-Befehl — du erstellst und bearbeitest die Datei manuell und commitest sie wie jede andere Datei. Jede nicht leere Zeile ist ein Muster, das gegen Dateipfade abgeglichen wird; eine Datei wird ignoriert, wenn sie auf ein Muster passt.

Einige Regeln gelten für das Dateiformat selbst:

• Eine leere Zeile passt auf nichts und dient nur der Lesbarkeit.
• Eine Zeile, die mit # beginnt, ist ein Kommentar. Um einen Dateinamen abzugleichen, der buchstäblich mit # beginnt, muss er als \# maskiert werden.
• Leerzeichen am Zeilenende werden ignoriert, sofern sie nicht mit einem Backslash (\) maskiert sind.
• Muster werden relativ zum Speicherort der .gitignore-Datei abgeglichen.

Die Muster selbst werden aus folgenden Symbolen aufgebaut:

Hier ist ein kleines .gitignore-Beispiel, das zeigt, wie sich debug?.log verhält (das ? passt auf genau ein Zeichen). Es ignoriert debug0.log und debug1.log, aber nicht debug10.log, weil 10 zwei Zeichen sind:

.gitignore patterns

debug?.log

# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)

Gemeinsame .gitignore-Dateien im Repository

Du kannst mehrere .gitignore-Dateien in verschiedenen Verzeichnissen eines Repositories anlegen. Jedes der Muster wird relativ zu dem Verzeichnis geprüft, das die jeweilige Datei enthält. Der einfachste Weg ist jedoch, eine einzelne .gitignore-Datei im Stammverzeichnis des Repositories zu definieren.

Da die .gitignore-Datei ins Repository eingecheckt ist, wird sie wie andere Dateien versioniert und beim Push mit dem Team geteilt. Du solltest in .gitignore nur Muster aufnehmen, die auch für andere Benutzer des Repositories sinnvoll sind.

Persönliche Regeln für Git ignore

Persönliche Ignorierregeln für ein einzelnes Repository können in der speziellen Datei .git/info/exclude gespeichert werden. Ihre Syntax ist identisch mit der von .gitignore, aber da das .git-Verzeichnis nicht zum Repository-Inhalt gehört, werden diese Regeln nicht versioniert und beim Push oder Klonen nicht geteilt. Verwende diese Datei für Editor-Backups, Scratch-Dateien oder alles, was nur für deinen eigenen Workflow relevant ist und dem restlichen Team nicht aufgezwungen werden soll.

Globale Git-Ignore-Regeln

Du kannst die Git-Eigenschaft core.excludesFile definieren, um zusätzliche globale Git-Ignore-Muster für alle Repositories auf deinem lokalen System anzugeben. Diese Datei wird von dir selbst erstellt. Du kannst deine globale .gitignore-Datei in deinem Home-Verzeichnis ablegen, damit sie leicht zu finden ist. Nachdem du die Datei erstellt hast, konfigurierst du ihren Speicherort mit dem Befehl git config wie folgt:

global gitignore rules

touch ~/.gitignore
git config --global core.excludesFile ~/.gitignore

Eine bereits committete Datei ignorieren

Das Hinzufügen eines Musters zu .gitignore stoppt Git nicht daran, eine bereits committete Datei weiter zu verfolgen — Ignorierregeln gelten nur für nicht verfolgte Dateien. Um eine solche Datei zu ignorieren, muss sie zunächst aus dem Git-Index entfernt werden. Verwende dazu git rm mit der Option --cached: Damit wird die Entfernung der Datei aus dem Repository gestaged, während die Kopie auf deiner Festplatte als ignorierte Datei erhalten bleibt. Anschließend wird die Änderung committet.

.gitignore committed files

echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"

Wenn die Datei auch aus deinem Arbeitsverzeichnis verschwinden soll, lasse --cached weg (git rm debug.log). Verwende anschließend git status, um zu bestätigen, dass die Datei weder als verfolgt noch als nicht verfolgt angezeigt wird.

Eine ignorierte Datei committen

Eine ignorierte Datei kann mit der Kombination der Option -f (oder --force) und git add ins Repository committet werden. Wähle diesen Weg, wenn du ein allgemeines Muster wie \*.log hast, aber eine bestimmte Datei trotzdem committen möchtest:

commiting ignored files

cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"

Andernfalls ist der einfachste Weg, eine Ausnahme zur allgemeinen Regel festzulegen:

commit ignored files

echo '!debug.log' >> .gitignore

cat .gitignore
#*.log
#!debug.log

git add debug.log
git commit -m "Adding debug.log"

Eine ignorierte Datei stashen

Der Befehl git stash nimmt deine nicht committeten gestageten und nicht gestageten Änderungen, speichert sie für später und setzt deine Arbeitskopie auf einen sauberen Zustand zurück. Standardmäßig werden nur Änderungen an verfolgten Dateien gestasht — ignorierte und nicht verfolgte Dateien bleiben an Ort und Stelle. Zwei Optionen erweitern diesen Umfang:

• git stash --include-untracked (oder -u) stasht zusätzlich nicht verfolgte Dateien.
• git stash --all (oder -a) stasht sowohl nicht verfolgte als auch ignorierte Dateien.

git stash --all

.gitignore-Dateien debuggen

Bei komplizierten Mustern oder Regeln, die über mehrere .gitignore-Dateien verteilt sind, kann es schwierig sein herauszufinden, welche Regel eine Datei versteckt. Der Befehl git check-ignore mit -v (oder --verbose) gibt das genaue verantwortliche Muster aus:

git check ignored files

git check-ignore -v debug.log
#.gitignore:3:*.log    debug.log

Die Ausgabe besteht aus vier durch Doppelpunkte getrennten Feldern (und einem Leerzeichen vor dem Dateinamen):

<file containing the pattern>:<line number of the pattern>:<pattern>    <file name>

.gitignore:3:*.log debug.log bedeutet also: Die Regel *.log in Zeile 3 von .gitignore bewirkt, dass debug.log ignoriert wird. Wenn der Befehl keine Ausgabe liefert, wird die Datei durch keine Regel ignoriert.

Verwandte Kapitel

• git rm — Dateien aus der Verfolgung entfernen, der Schlüssel zum Ignorieren einer bereits committeten Datei.
• git add — Dateien stagen, einschließlich -f, um eine ignorierte Datei zwangsweise hinzuzufügen.
• git stash — Änderungen beiseitelegen; mit --all kombinieren, um auch ignorierte Dateien einzuschließen.
• git config — core.excludesFile für eine globale Ignore-Liste setzen.
• git clean — Nicht verfolgte Dateien löschen; mit -x kombinieren, um auch ignorierte Dateien zu entfernen.

Übungen