Die Datei .gitignore: Dateien von Git ausschließen und bereits hinzugefügte entfernen

Der Mechanismus git ignore ist die Art, Git zu sagen: „Diese Dateien nicht anfassen, nicht in git status anzeigen und nicht mit git add . hinzufügen.“ Die Regeln stehen in der Textdatei .gitignore, die mit dem Projekt committet wird und für das ganze Team gilt. Die wichtigste Feinheit: Das Ignorieren wirkt nur auf Dateien, die Git noch nicht verfolgt.

Was gehört typischerweise in .gitignore?

• Abhängigkeiten: node_modules/, vendor/, .venv/ – der Paketmanager stellt sie wieder her.
• Build-Ergebnisse: dist/, build/, *.class, __pycache__/.
• Logs und temporäre Dateien: *.log, tmp/, *.swp.
• Secrets und lokale Einstellungen: .env, Schlüssel, lokale Konfigurationen.
• Datenmüll von Betriebssystem und Editoren: .DS_Store, Thumbs.db, .idea/ – die gehören allerdings besser ins globale Ignore, dazu unten mehr.

Die Regel ist einfach: Ins Repository gehört, was Menschen schreiben, nicht das, was Programme erzeugen oder was von einem bestimmten Rechner abhängt.

.gitignore erstellen

Es ist eine normale Textdatei im Wurzelverzeichnis des Repositorys. Legen Sie sie an, tragen Sie die Muster zeilenweise ein und committen Sie sie:

cat > .gitignore <<'EOF'
# Abhängigkeiten
node_modules/
# Build
dist/
# Logs
*.log
# Secrets
.env
EOF

git add .gitignore
git commit -m "chore: .gitignore hinzugefügt"

Fertige Vorlagen für gängige Sprachen und Frameworks finden Sie im Repository github/gitignore; GitHub und GitLab bieten beim Anlegen eines Projekts die Auswahl einer Vorlage an. Nehmen Sie diese als Grundlage und entfernen Sie Überflüssiges.

Syntax der .gitignore-Muster

Wichtiges Detail: Ein Muster ohne Schrägstrich im Inneren (config.json) greift auf jeder Ebene, ein Muster mit Schrägstrich am Anfang oder in der Mitte (/config.json, src/config.json) relativ zum Ordner, in dem diese .gitignore liegt.

Ausnahmen mit Ausrufezeichen

*.log
!important.log

Die Falle: Eine Datei lässt sich nicht „zurückholen“, wenn ihr übergeordneter Ordner ignoriert wird. Git betritt ignorierte Ordner nicht, daher funktioniert Folgendes nicht:

logs/
!logs/keep.txt     # funktioniert nicht

Richtig ist, den Inhalt zu ignorieren, nicht den Ordner:

logs/*
!logs/keep.txt

Mit demselben Trick behält man einen leeren Ordner im Repository: Git speichert keine leeren Verzeichnisse, deshalb legt man eine Datei .gitkeep hinein und erlaubt nur diese.

Wo sich Ignore-Regeln sonst noch festlegen lassen

Datenmüll Ihres Betriebssystems und Ihrer IDE gehört sinnvollerweise ins globale Ignore, damit die gemeinsame .gitignore nicht zugemüllt wird:

git config --global core.excludesFile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global

Ist core.excludesFile nicht gesetzt, liest Git ~/.config/git/ignore, sofern die Datei existiert.

Warum .gitignore nicht funktioniert

Die häufigste Beschwerde: „Ich habe die Datei in .gitignore eingetragen, aber Git zeigt trotzdem Änderungen an.“ Der Grund ist fast immer derselbe – die Datei wird bereits verfolgt. Ignore-Regeln wirken nicht auf Dateien, die einmal in einem Commit gelandet sind.

Welche Regel greift (oder warum keine greift), prüfen Sie mit git check-ignore:

git check-ignore -v logs/app.log
# .gitignore:3:*.log	logs/app.log

Die Ausgabe zeigt Datei und Zeile der Regel. Eine leere Ausgabe bedeutet, dass die Datei nicht ignoriert wird. Weitere Fehlerquellen sind Leerzeichen am Ende einer Musterzeile oder eine falsche Kodierung der Datei (etwa UTF-16, wenn sie mit PowerShell erstellt wurde).

Bereits committete Dateien aus dem Repository entfernen: git rm --cached

Der Befehl git rm entfernt eine Datei aus dem Index und von der Festplatte. Mit dem Flag --cached nur aus dem Index: Die Datei bleibt bei Ihnen erhalten, wird aber nicht mehr verfolgt.

echo ".env" >> .gitignore
git rm --cached .env
git commit -m "chore: .env wird nicht mehr getrackt"
git push

Für einen Ordner brauchen Sie -r:

git rm -r --cached node_modules/

Gibt es viele Regeln und ist unklar, was bereits im Repository gelandet ist, können Sie den Index komplett neu aufbauen: git rm -r --cached ., dann git add . und ein Commit. Prüfen Sie vor dem Commit git status – dort sehen Sie die aus dem Index entfernten Dateien.

Achtung: Secrets bleiben in der Historie

git rm --cached entfernt die Datei aus den folgenden Commits, aber nicht aus den vergangenen. Ist ein Passwort oder Token ins Repository gelangt, kann es jeder mit einem Klon in der Historie finden. Das Secret gilt als kompromittiert und muss neu ausgestellt werden. Die Historie lässt sich mit Werkzeugen wie git filter-repo umschreiben, das ändert aber die Hashes aller nachfolgenden Commits und erfordert Abstimmung im Team.

Eine weitere Folge: Bei Kollegen wird eine per --cached aus dem Index entfernte Datei nach git pull von der Festplatte gelöscht. Bei .env sollten Sie das Team vorab informieren oder eine Vorlage .env.example im Repository pflegen.

git rm: Dateien löschen

git rm old.py              # von der Festplatte und aus dem Index löschen
git rm -r legacy/          # Ordner löschen
git rm -n '*.tmp'          # Dry Run: anzeigen, was gelöscht würde
git rm -f changed.py       # Datei mit nicht committeten Änderungen löschen

Löschen Sie eine Datei mit einem normalen rm, sieht Git sie als „deleted“, und Sie müssen das Löschen per git add oder git rm vormerken. git rm erledigt beide Schritte auf einmal. Ohne -f verweigert es das Löschen einer Datei mit nicht committeten Änderungen – ein Schutz vor Arbeitsverlust.

git mv: umbenennen und verschieben

git mv utils.py helpers.py
git mv helpers.py src/helpers.py

git mv ist eine Abkürzung für mv + git rm des alten Pfads + git add des neuen. Git speichert die Umbenennung nicht als solche: Es erkennt sie anhand der Ähnlichkeit des Inhalts bei der Ausgabe von git status, git log --follow und git diff. Deshalb führen eine Umbenennung mit git mv und ein normales mv mit anschließendem git add -A zum selben Ergebnis.

Praxistipp: Benennen Sie eine Datei um und ändern Sie ihren Inhalt in getrennten Commits. Hat sich die Datei zusammen mit der Umbenennung stark verändert, erkennt Git sie womöglich nicht als dieselbe Datei, und die Historie über --follow reißt ab.

Um unter Windows und macOS (Dateisysteme ohne Unterscheidung von Groß- und Kleinschreibung) nur die Schreibweise eines Namens zu ändern, verwenden Sie git mv readme.md README.md – eine einfache Umbenennung im Dateimanager bemerkt Git unter Umständen nicht.

Reihenfolge und Priorität der Regeln

Innerhalb einer Datei werden die Regeln von oben nach unten gelesen, und die letzte passende gewinnt. Daher muss die Ausnahme !keep.log unterhalb der Regel *.log stehen, sonst wird sie überdeckt. Zwischen den Dateien gilt: Eine .gitignore in einem Unterordner hat Vorrang vor der im Wurzelverzeichnis, globales Ignore und .git/info/exclude haben die niedrigste Priorität.

Beispiel einer .gitignore für ein Webprojekt

Hier eine praxistaugliche Variante für ein Node.js-Projekt mit Python-Backend. Achten Sie auf die Kommentare: In einem halben Jahr weiß niemand mehr, warum eine bestimmte Regel hinzugefügt wurde.

# --- Abhängigkeiten ---
node_modules/
.venv/

# --- Build und Caches ---
/dist
/build
__pycache__/
*.pyc
.pytest_cache/
coverage/

# --- Logs ---
*.log
npm-debug.log*

# --- Umgebung und Secrets ---
.env
.env.*
!.env.example

# --- Benutzer-Uploads, aber den Ordner behalten ---
uploads/*
!uploads/.gitkeep

Hier kommen beide Ausnahme-Tricks zum Einsatz: .env.* blendet alle lokalen Umgebungsvarianten aus, die Vorlage .env.example bleibt aber im Repository, und der Ordner uploads existiert im Klon dank .gitkeep.

Was Sie nicht ignorieren sollten

Zu viel zu ignorieren schadet ebenfalls. Lock-Dateien der Abhängigkeiten – package-lock.json, poetry.lock, composer.lock – werden in Anwendungen üblicherweise committet: Sie stellen sicher, dass alle Entwickler und die CI dieselben Paketversionen installieren. Gemeinsame Formatierungseinstellungen (.editorconfig, Linter-Konfigurationen) gehören ebenfalls ins Repository.

Ein Grenzfall sind IDE-Einstellungen. Der Ordner .vscode/ wird oft komplett ignoriert, manchmal aber werden empfohlene Erweiterungen und Build-Tasks committet: .vscode/*, danach !.vscode/extensions.json. Die Entscheidung trifft das Team – wichtig ist nur, keine persönlichen Pfade und Schlüssel im gemeinsamen Repository zu haben.

Szenario: node_modules versehentlich committet

Ein klassischer Anfängerfehler: git add . vor dem Anlegen der .gitignore, und Zehntausende Dateien landen im Commit. Die Korrektur in drei Schritten:

echo "node_modules/" >> .gitignore
git rm -r --cached node_modules
git commit -m "chore: node_modules aus dem Repository entfernt"

Ist der Commit noch nicht auf den Server gepusht, schreiben Sie ihn besser um, damit die schweren Dateien nicht in der Historie bleiben: git reset --soft HEAD~1, dann dieselben Befehle und ein neuer Commit. Nach dem Push sind die Dateien bereits in der Historie, und die Klongröße sinkt nicht, ohne die Historie umzuschreiben.

Damit sich das nicht wiederholt, legen Sie .gitignore vor dem ersten git add an und gewöhnen Sie sich an, vor dem Commit git status anzusehen: Eine verdächtig lange Liste neuer Dateien ist ein Grund innezuhalten.

Fazit

Die Datei .gitignore ist die erste Datei, die Sie in einem neuen Projekt committen sollten: Abhängigkeiten, Builds, Logs und Secrets haben im Repository nichts zu suchen. Ignore-Regeln wirken nur auf nicht getrackte Dateien, daher entfernen Sie bereits Hinzugefügtes mit git rm --cached und prüfen die Regeln mit git check-ignore -v. Zum Löschen und Umbenennen verwenden Sie git rm und git mv, damit die Änderungen direkt im Index landen. Die Arbeit mit dem Index und dem ersten Repository üben wir praktisch in unserem Git-Kurs.