gitignore-Leitfaden: Dateien ausschließen und Vorlagen nutzen

Eine .gitignore-Datei sagt Git, welche Dateien es ignorieren soll, und ein guter gitignore-Einsatz bewahrt dein Repository davor, mit Build-Ausgaben, geheimen Schlüsseln und Editor-Resten aufzuquellen. Sobald Dateien wie node_modules/, vendor/, .env oder .DS_Store in der Historie landen, wächst dein Repo unnötig und eines Tages veröffentlichst du womöglich versehentlich jemandes Passwort. Dieser Artikel zeigt den richtigen Weg, Dateien auszuschließen, die Muster-Syntax und die häufigsten Fehler.

Eine Regel vorweg: .gitignore wirkt nur auf Dateien, die noch nicht versioniert (untracked) sind. Eine Datei zur Ignorierliste hinzuzufügen, nachdem du sie committet hast, entfernt sie nicht automatisch — das ist die häufigste Verwirrung, und ich habe ihr unten einen eigenen Abschnitt gewidmet.

Wohin gehört die .gitignore?

In den meisten Projekten lebt eine einzige .gitignore im Stammverzeichnis des Repositories und wird selbst committet, sodass das ganze Team dieselben Regeln teilt. Doch Git unterstützt mehrere Ebenen:

• Stamm-.gitignore — gemeinsame Regeln für das gesamte Projekt; Teil der Versionsverwaltung.
• Unterverzeichnis-.gitignore — eine zusätzliche Datei in einem beliebigen Ordner gilt nur für diesen Ordner und darunter. Pfade sind relativ zu diesem Verzeichnis.
• .git/info/exclude — Regeln nur für deine Maschine; werden nie committet oder geteilt.
• Globale gitignore — persönliche Regeln, die auf all deine Repositories angewendet werden (siehe unten).

Tiefer liegende, später gelesene Dateien können die obigen überschreiben. So kann eine .gitignore in einem Unterordner per Negation eine Regel wieder einschließen, die die Stamm-Datei ausgeschlossen hatte.

Muster-Syntax

Jede Zeile ist ein Muster. Leerzeilen werden ignoriert, Zeilen, die mit # beginnen, sind Kommentare. Die Grundlagen:

# Kommentarzeile
*.log              # alle .log-Dateien (in jedem Verzeichnis)
build/             # ein abschließendes / passt nur auf Verzeichnisse
/config.local      # ein führendes / verankert das Muster am Repo-Stamm
temp?.txt          # ? passt auf ein einzelnes Zeichen
cache[0-9].dat     # eckige Klammern bilden einen Zeichenbereich
!important.log      # ! Negation: diese Datei dennoch versionieren

Wichtige Unterschiede:

• * passt auf alles außer dem Schrägstrich (/); ** überschreitet Verzeichnisgrenzen. Zum Beispiel erfasst logs/**/*.log die .log-Dateien in jeder Tiefe unter logs.
• Ein führendes / verankert das Muster am Stamm: /build schließt nur den build-Ordner im Stamm aus, nicht die build-Ordner in Unterverzeichnissen.
• Ein abschließendes / zielt nur auf Verzeichnisse: build/ schließt keine gleichnamige Datei aus.
• ! schließt eine durch eine frühere Regel ausgeschlossene Datei wieder ein — aber wenn der übergeordnete Ordner der Datei vollständig ignoriert wird, hilft die Negation nicht, denn Git schaut nie in diesen Ordner hinein.

Ein typisches .gitignore-Beispiel

In einem Laravel-+-Node-Projekt sieht die Stamm-.gitignore ungefähr so aus:

# Abhängigkeiten
/node_modules
/vendor

# Umgebung und Geheimnisse
.env
.env.*
!.env.example

# Build-Ausgabe
/public/build
/dist

# Logs und temporäre Dateien
*.log
/storage/*.key

# Editor und Betriebssystem
.DS_Store
.idea/
.vscode/
Thumbs.db

Beachte: .env.* schließt jede Umgebungsdatei aus, während die Zeile !.env.example die Beispielvorlage bewusst versioniert hält — neue Entwickler füllen damit ihre eigene .env.

Eine bereits versionierte Datei ausschließen

Angenommen, du hast vergessen, node_modules/ von Anfang an zu ignorieren, und es committet. Es jetzt zur .gitignore hinzuzufügen, reicht nicht; du musst die Dateien aus Gits Versionierung nehmen. Die Lösung besteht darin, sie aus dem Index zu entfernen, ohne sie von der Festplatte zu löschen:

git rm -r --cached node_modules
git commit -m "chore: node_modules nicht mehr versionieren"

Das Flag --cached ist entscheidend: Die Dateien bleiben im Arbeitsverzeichnis und verlassen nur Gits Index. Nach diesem Commit greift die .gitignore-Regel und die Dateien werden nicht erneut hinzugefügt. Für eine einzelne Datei genügt git rm --cached datei.

Globale gitignore: persönliche Reste überall stummschalten

Dateien wie .DS_Store, .idea/ oder *.swp sind spezifisch für dein Betriebssystem oder deinen Editor; sie in die .gitignore jedes Projekts aufzunehmen, ist gegenüber deinen Teamkollegen unfair. Der richtige Ansatz ist eine globale gitignore:

git config --global core.excludesFile ~/.gitignore_global

Anschließend schreibst du deine persönlichen Muster in ~/.gitignore_global. Diese Regeln gelten nur auf deiner Maschine, über all deine Repositories, ohne die Projektdatei zu verschmutzen.

Fertige Vorlagen und Fehlersuche

Du musst nicht jede Sprache von Grund auf schreiben. Das offizielle Repository github/gitignore hostet fertige Vorlagen für Hunderte von Sprachen und Werkzeugen, während gitignore.io anhand der gewählten Technologien eine kombinierte Datei erzeugt. Nimm sie als Ausgangspunkt und kürze dann auf dein Projekt zu.

Willst du wissen, warum eine Datei ignoriert wird, rate nicht — frag Git:

git check-ignore -v dist/app.js

Dieser Befehl zeigt, welche Zeile welcher .gitignore die Datei ausgeschlossen hat. Musst du eine ignorierte Datei dennoch hinzufügen, kannst du es mit git add -f datei erzwingen.

Häufige Fragen

Warum wird eine zur .gitignore hinzugefügte Datei trotzdem committet?

Höchstwahrscheinlich wird die Datei bereits versioniert. .gitignore wirkt nur auf unversionierte Dateien. Entferne sie mit git rm --cached datei aus dem Index und committe dann; die Regel greift danach.

Wie nehme ich einen leeren Ordner ins Repo auf?

Git versioniert keine leeren Verzeichnisse. Üblich ist, eine leere Datei namens .gitkeep in den Ordner zu legen (keine offizielle Git-Funktion, nur eine Konvention) und diese Datei zu committen, damit der Ordner erhalten bleibt.

Ich habe versehentlich eine .env-Datei veröffentlicht — was tun?

Nimm die Datei zuerst mit git rm --cached .env aus der Versionierung und füge sie der .gitignore hinzu. Aber denk daran, dass sie in alten Commits bleibt: War sie wirklich geheim, ändere/erneuere sofort alle Passwörter und Tokens darin — die Historie zu bereinigen ist für sich allein keine ausreichende Sicherheit.

Deine Repositories sauber zu halten, ist ein kleiner, aber dauerhafter Gewinn. Wenn du deine Git-Einrichtung, deinen Deploy-Ablauf oder den korrekten Start eines Projekts vom ersten Tag an gemeinsam durchgehen möchtest, nimm Kontakt mit mir auf.