Was ist eine .gitignore-Datei? Wie funktioniert sie – mit Beispielen

 Eine .gitignore-Datei ist eine reine Textdatei, die Git mitteilt, welche Dateien und Ordner aus deinem Repository ausgeschlossen werden sollen. Du listest auf, was ignoriert werden soll – ein Muster pro Zeile –, und Git bietet diese Dateien nicht mehr an, wenn du deine Arbeit stagest und committest.

Falls du schon einmal ein Projekt geöffnet und neben dem Programmcode eine Datei namens .gitignore gefunden hast, erklärt dir dieser Leitfaden, was sie dort zu suchen hat. Er behandelt, wie die Datei funktioniert, was normalerweise darin steht, die Musterregeln und wie du das häufigste Problem beheben kannst: eine Datei, die Git weiterhin verfolgt, obwohl du sie ignoriert hast.

So funktioniert eine .gitignore-Datei

Das Wichtigste auf einen Blick: Git liest die .gitignore-Datei, bevor es entscheidet, welche neuen Dateien es dir anzeigt, und überspringt alles, was einem darin enthaltenen Muster entspricht.

Git ist das Tool, das die meisten Entwickler nutzen, um Änderungen an ihrem Code zu verfolgen. Es überwacht einen Projektordner und erkennt jede neue oder geänderte Datei. Ohne Anweisungen würde es vorschlagen, alles zu speichern – einschließlich Passwörtern, heruntergeladenen Bibliotheken und temporären Dateien, die dein Computer von selbst erstellt.

Eine .gitignore-Datei ist genau diese Reihe von Anweisungen. Sie befindet sich normalerweise im obersten Ordner eines Projekts, und jede Zeile beschreibt Dateien, die übersprungen werden sollen. Wenn du „git status“ ausführst, um zu sehen, was sich geändert hat, oder „git add“, um Dateien für einen Commit vorzubereiten, vergleicht Git jede neue Datei mit diesen Zeilen. Übereinstimmende Dateien bleiben unsichtbar.

Die Datei wirkt sich nur auf Dateien aus, die Git noch nicht verfolgt. In der Git-Dokumentation wird ihr Zweck so beschrieben, dass nicht verfolgte Dateien auch nicht verfolgt werden; eine Datei, die bereits committet wurde, bleibt also weiterhin verfolgt, bis du sie aus der Verfolgung entfernst (siehe häufige Fehler weiter unten). Ein paar weitere Details bestimmen, wie sie sich verhält:

• Die „.gitignore“-Datei wird wie jede andere Datei committet, sodass jeder, der das Projekt klont, die gleichen Regeln erhält.
• Eine .gitignore-Datei in einem Unterordner gilt für diesen Ordner und alles, was sich darin befindet.
• Regeln, die nur auf deinem Rechner relevant sind, wie zum Beispiel Dateien, die dein eigener Editor erstellt, kannst du in eine globale Ignore-Datei oder in „.git/info/exclude“ schreiben, das niemals geteilt wird.

Was du in eine .gitignore-Datei schreiben solltest

Das Wichtigste auf einen Blick: Ignoriere alles, was geheim ist, alles, was neu erstellt werden kann, und alles, was spezifisch für den Rechner einer bestimmten Person ist.

Die meisten Einträge lassen sich in fünf Gruppen einteilen:

Hier ist eine kurze .gitignore-Datei für ein typisches Webprojekt. Zeilen, die mit # beginnen, sind Kommentare, die Git überspringt.

# Secrets and local settings
.env
.env.local

# Dependencies
node_modules/
vendor/

# Build output
dist/

# Logs
*.log

# Editor and operating system files
.DS_Store
.idea/
.vscode/

Du musst selten eine von Grund auf neu schreiben. GitHub unterhält eine öffentliche Sammlung von .gitignore-Vorlagen für die meisten Sprachen und Frameworks, und viele Projekt-Starter erstellen eine für dich.

Sollte .env in .gitignore stehen?

Das Wichtigste auf einen Blick: Ja. Ignoriere deine .env-Datei und committe eine .env.example mit Platzhalterwerten, damit deine Teamkollegen wissen, welche Einstellungen das Projekt benötigt.

Eine .env-Datei enthält Einstellungen, die deine App beim Start liest, darunter oft Datenbankpasswörter und API-Schlüssel. (Unser Leitfaden „Was ist .env?“ behandelt das Thema ausführlich.) Da diese Werte geheim sind, steht die .env-Datei normalerweise an erster Stelle in jeder .gitignore-Datei.

Ein neuer Teamkollege, der das Projekt klont, erhält keine .env-Datei und kann daher nicht erkennen, welche Einstellungen die App erwartet. Die gängige Lösung ist eine zweite Datei, .env.example, die dieselben Namen mit Dummy-Werten auflistet. Es ist sicher, diese zu committen, da nichts darin echt ist. Jeder Entwickler kopiert sie in .env und füllt seine eigenen Werte ein.

# .env.example
DATABASE_URL=your-database-url-here
PAYMENT_API_KEY=your-key-here

Das Ignorieren von .env schützt dich von nun an. Es macht die Vergangenheit nicht ungeschehen: Wenn ein Geheimnis jemals committet wurde, bleibt es in der Historie des Projekts. Die sichere Vorgehensweise ist, dieses Passwort oder diesen Schlüssel durch ein neues zu ersetzen und die Datei anschließend aus der Verfolgung zu entfernen.

Verhindert „.gitignore“, dass KI-Programmieragenten „.env“ lesen?

Das Wichtigste auf einen Blick: Nein. .gitignore hält Dateien aus Git heraus, nicht jedoch außer Reichweite. KI-Programmierassistenten auf deinem Rechner können alles lesen, was dein Benutzerkonto lesen kann.

Ein KI-Programmieragent wie Cursor, Claude Code oder Codex arbeitet in deinem Projektordner und hat denselben Zugriff auf Dateien wie du. .gitignore teilt Git mit, was bei Commits ausgelassen werden soll. Es verbirgt Dateien nicht vor anderen Programmen, die auf deinem Computer laufen – daher kann ein Agent deine .env-Datei öffnen, ihre Werte ausgeben oder sie in einen Chat einfügen.

Die meisten Tools bieten dir eine separate Möglichkeit, Agenten von sensiblen Dateien fernzuhalten:

• Cursor überspringt standardmäßig die in der `.gitignore` aufgeführten Dateien sowie `.env`-Dateien, und du kannst weitere Muster in einer `.cursorignore`-Datei hinzufügen. In der Dokumentation von Cursor wird darauf hingewiesen, dass das Terminal und die MCP-Tools des Agenten ignorierte Dateien weiterhin lesen können.
• Bei Claude Code kannst du in der Konfigurationsdatei Sperrregeln hinzufügen, zum Beispiel eine Regel, die das Lesen von .env-Dateien blockiert.

Betrachte diese als Sicherheitsnetz, nicht als Garantie. Die sicherste Vorgehensweise ist, nur Entwicklungs- oder Testschlüssel in deiner lokalen .env-Datei zu speichern und Produktionsgeheimnisse komplett von deinem Rechner fernzuhalten.

Spickzettel zur .gitignore-Syntax

Das Wichtigste auf einen Blick: Mit einer Handvoll Symbole lassen sich fast alle Fälle abdecken. Ein abschließender Schrägstrich bedeutet „nur Ordner“, ein Sternchen passt auf beliebige Zeichen und ein Ausrufezeichen bildet eine Ausnahme.

Zwei Regeln bereiten den meisten Leuten Schwierigkeiten. Erstens: Wenn zwei Zeilen widersprechen, hat die spätere Vorrang – setze Ausnahmen also hinter die Regel, die sie außer Kraft setzen. Zweitens: Du kannst keine Ausnahme für eine Datei in einem Ordner festlegen, den du komplett ignoriert hast, da Git niemals in diesen Ordner hineinschaut. Ignoriere den Inhalt des Ordners (logs/*) statt des Ordners selbst, wenn du darin Ausnahmen benötigst.

Häufige Fehler in der .gitignore-Datei und wie man sie behebt

Das Wichtigste: Wenn Git eine von dir ignorierte Datei immer noch nachverfolgt, wurde sie zuvor committet. Entferne sie mit `git rm --cached` aus der Nachverfolgung und committe die Änderung.

Die Datei wurde bereits committet

Das ist meist der Grund, warum eine .gitignore-Datei scheinbar nicht funktioniert. Git ignoriert nur Dateien, die es noch nicht verfolgt. Um die Verfolgung einer Datei zu beenden, aber deine lokale Kopie zu behalten, führe Folgendes aus:

git rm --cached .env
git commit -m "Stop tracking .env"

Für einen ganzen Ordner füge -r hinzu, wie in `git rm -r --cached node_modules`. Deine Dateien bleiben auf deinem Computer. Sie verschwinden ab dem nächsten Commit aus dem Repository, bleiben aber in dessen Historie erhalten.

Das Muster stimmt nicht mit dem überein, was du denkst

Um zu sehen, welche Zeile in welcher Datei einen Pfad ignoriert, führe `git check-ignore -v` gefolgt vom Pfad aus. Wenn nichts ausgegeben wird, passt keine Regel darauf.

Es gibt einen Haken: Standardmäßig überspringt der Befehl Dateien, die Git bereits verfolgt, sodass er für diese nichts ausgibt, selbst wenn eine Regel passt. Füge `--no-index` hinzu, um eine dieser Dateien zu überprüfen:

`git check-ignore -v --no-index .env`

Die Datei befindet sich am falschen Ort oder hat den falschen Namen

Die Datei muss genau .gitignore heißen, mit dem führenden Punkt und ohne Dateiendung. Notepad unter Windows kann sie beispielsweise als .gitignore.txt speichern. Muster werden zudem relativ zu dem Ordner gelesen, in dem sich die .gitignore-Datei befindet.

Persönliche Dateien in der gemeinsamen Datei

Dateien, die nur deine Installation erstellt, wie zum Beispiel der Einstellungsordner eines Editors, solltest du besser in deiner globalen Ignore-Datei speichern. So bleibt die gemeinsam genutzte .gitignore auf das konzentriert, was für das gesamte Projekt wichtig ist.

Nach Sprache und Framework

Das Wichtigste auf einen Blick: Jede Sprache hinterlässt ihre eigenen Spuren in Form von installierten Paketen und Build-Dateien. Ignoriere diese und behalte die Dateien, die beschreiben, was installiert werden soll.

Die zuvor erwähnten Geheimnisse und Editor-Unordnung gelten für jedes Projekt. Was sonst noch ignoriert werden sollte, hängt von der Sprache ab, da jede Sprache Pakete und Build-Dateien in ihren eigenen Ordnern installiert:

Das Muster ist in jeder Zeile dasselbe. Ignoriere, was neu kompiliert werden kann, und committe die Dateien, die beschreiben, wie es neu kompiliert wird, einschließlich der Lock-Datei. Unser Leitfaden „Was ist eine Lock-Datei?“ erklärt, warum die Lock-Datei in Git gehört.

Viele Frameworks erstellen beim Start eines neuen Projekts eine .gitignore-Vorlage für dich, darunter Laravel und Rails. Überprüfe also, was bereits vorhanden ist, bevor du Zeilen hinzufügst. Für alles, was fehlt, bietet die Sammlung von .gitignore-Vorlagen auf GitHub für die meisten Sprachen und Frameworks eine vorgefertigte Datei.

Wie Upsun cloud mit Geheimnissen umgeht, ohne dass Dateien committet werden

Das Wichtigste auf einen Blick: Bei Upsun Cloud liegen Geheimnisse in Variablen auf Projekt- oder Umgebungsebene, nicht in Dateien. Deine .env-Datei kann also ignoriert bleiben, und deine App erhält trotzdem die Werte, die sie braucht.

Upsun Cloud erstellt und stellt deine App aus deinem Git-Repository bereit, sodass eine ignorierte .env-Datei sie niemals erreicht.

Die eigentlichen Passwörter stammen aus Variablen, die du in Upsun Cloud selbst festlegst – über die Konsole oder die Befehlszeile. Dabei spielen zwei Ebenen eine Rolle:

• Projektvariablen gelten für jede Umgebung. Sie eignen sich für Geheimnisse, die überall gleich sind, wie zum Beispiel Anmeldedaten für einen gemeinsam genutzten Dienst.
• Variablen auf Umgebungsebene gelten für eine bestimmte Umgebung, wie zum Beispiel die Produktionsumgebung. Sie eignen sich für Werte, die sich unterscheiden, wie zum Beispiel die Verwendung von Test-Zahlungsschlüsseln in einer Vorschauumgebung und von Live-Schlüsseln in der Produktivumgebung.

Ein paar Optionen sorgen dafür, dass das in der Praxis funktioniert. Wenn du eine Variable als sensibel markierst, wird ihr Wert in der Konsole und in der Befehlszeilenausgabe ausgeblendet, während deine App ihn weiterhin lesen kann. Ein nur für die Produktivumgebung bestimmtes Geheimnis kann so festgelegt werden, dass andere Umgebungen es nicht übernehmen. Und wenn du einer Variable das Präfix „env:“ gibst, wird sie deiner App als gewöhnliche Umgebungsvariable zur Verfügung gestellt, sodass du Programme nicht mehr programmieren musst, um ihre Einstellungen aus der Umgebung zu lesen.

Dieser Befehl speichert zum Beispiel einen Zahlungsschlüssel, der nur für die Produktivumgebung bestimmt ist, verborgen bleibt und nicht an andere Umgebungen weitergegeben wird:

upsun variable:create --level environment -e main --name env:PAYMENT_API_KEY --value dein-Schlüssel-hier --sensitive true --inheritable false

In der Upsun-Dokumentation wird außerdem darauf hingewiesen, dass Werte, die du in der projektinternen Konfigurationsdatei festlegst, in Git committet werden, weshalb sie sich schlecht als Geheimnisse eignen. Nutze diese Datei für Einstellungen, die du bedenkenlos teilen kannst. So hält .gitignore Geheimnisse aus deinem Programm fern, und Upsun-cloud-Variablen stellen sie der laufenden App zur Verfügung. Alle Optionen findest du unter „Variablen festlegen“ in der Upsun-Dokumentation.

Ignoriere die .environment-Datei nicht

Upsun Cloud liest .env-Dateien überhaupt nicht. Stattdessen liest es eine andere Datei, nämlich .environment, aus dem Stammordner deiner App. Diese Datei wird beim Start des Containers deiner App als Skript ausgeführt und kann Umgebungsvariablen für die App setzen. Projekte, die mit `upsun project:init` eingerichtet wurden, verfügen möglicherweise bereits über eine solche Datei, beispielsweise um Datenbankdetails in der von einem Framework erwarteten Form zu übergeben.

Trotz des ähnlichen Namens muss die „.environment“-Datei committet werden, damit Upsun Cloud sie nutzen kann. Überprüfe, ob kein Muster in deiner „.gitignore“-Datei, wie z. B. „.env*“, sie versehentlich ausklammert. Da sie committet wird, solltest du auch keine vertraulichen Daten darin speichern: Sie sollte auf Variablen verweisen, aber keine Passwörter enthalten.

Upsun Cloud baut jede Umgebung aus deinem Git-Repository auf und speichert geheime Daten in Variablen, sodass ein sauberes .gitignore-File alles ist, was dein Repository benötigt. Du kannst 15 Tage lang kostenlos auf Upsun Cloud bereitstellen, ganz ohne Kreditkarte, oder dir ansehen, wie Git-gesteuerte Automatisierung funktioniert.

Häufig gestellte Fragen (FAQ)

Wozu dient eine .gitignore-Datei?

Sie teilt Git mit, welche Dateien und Ordner aus einem Repository ausgeschlossen werden sollen. Teams nutzen sie, um Geheimnisse, installierte Bibliotheken, Build-Ergebnisse und maschinenspezifische Dateien aus dem gemeinsam genutzten Code herauszuhalten.

Wo sollte die .gitignore-Datei abgelegt werden?

Normalerweise im obersten Ordner des Projekts, neben dem versteckten .git-Ordner. Du kannst weitere .gitignore-Dateien in Unterordnern hinzufügen, wobei jede für ihren eigenen Ordner und alles darunter gilt.

Soll ich die .gitignore-Datei committen?

Ja. Wenn du sie eincheckst, bedeutet das, dass alle, die an dem Projekt arbeiten, dieselben Dateien ignorieren.

Warum funktioniert meine .gitignore-Datei nicht?

Die Datei wurde höchstwahrscheinlich bereits committet, bevor du die Regel hinzugefügt hast. Führe „git rm --cached“ darauf aus und committe sie. Wenn das nicht die Ursache ist, führe „git check-ignore -v“ mit dem Dateipfad aus, um zu sehen, welche Regel gegebenenfalls gilt.

Löscht „.gitignore“ Dateien?

Nein. Ignorierte Dateien bleiben auf deinem Computer. Git bietet sie einfach nicht mehr zum Committen an.

Verhindert .gitignore, dass KI-Programmieragenten meine .env-Datei lesen?

Nein. Es steuert nur, was Git committet. Nutze die Ignorier- oder Berechtigungseinstellungen deines Programmier-Tools, wie zum Beispiel eine „.cursorignore“-Datei in Cursor oder „deny“-Regeln in Claude Code, und halte Produktionsgeheimnisse aus deiner lokalen „.env“-Datei heraus.

Entfernt .gitignore Geheimnisse, die bereits committet wurden?

Nein. Alles, was einmal committet wurde, bleibt im Projektverlauf erhalten. Ersetze das offengelegte Passwort oder den Schlüssel durch ein neues bzw. einen neuen und hebe dann die Verfolgung der Datei auf.

Was ist der Unterschied zwischen .gitignore und .git/info/exclude?

Beide verwenden dieselben Musterregeln. Die .gitignore-Datei wird über das Repository für alle freigegeben, während .git/info/exclude nur auf deinem Rechner verbleibt.