.gitignore funktioniert nicht: Bereits getrackte Dateien freigeben

Inhalt
Sie haben in der .gitignore im Projektstamm die richtige Regel eingetragen, trotzdem taucht die Datei weiter in git status auf und landet auch im Commit. Die Regel noch einmal neu zu schreiben, ändert daran nichts.
Die Ursache ist kein Tippfehler, sondern der Geltungsbereich. Die offizielle Git-Dokumentation beschreibt die .gitignore als Datei, die festlegt, welche Dateien absichtlich nicht verfolgt werden sollen, und hält ausdrücklich fest: Dateien, die Git bereits verfolgt, sind davon nicht betroffen. Eine Datei, die einmal mit git add in den Index aufgenommen wurde, wird weiterverfolgt, egal was in den Regeln steht.
Kurzfassung ① Die
.gitignoregilt nur für Dateien, die noch nicht verfolgt werden. Auf bereits verfolgte Dateien hat sie keinerlei Wirkung. ② Mitgit ls-files --error-unmatch <Pfad>prüfen Sie, ob eine Datei verfolgt wird, mitgit check-ignore -v --no-index <Pfad>, ob eine Regel greift. Beides sind getrennte Prüfungen. ③ Die Verfolgung beenden Sie mitgit rm --cached <Pfad>. Die Datei im Arbeitsverzeichnis bleibt erhalten, sie wird nur aus dem Index entfernt.
Warum die Datei trotz korrekter Regel weiter auftaucht
Git teilt Dateien in zwei Gruppen ein: verfolgte Dateien (englisch „tracked"), die im Index (der Staging-Area) eingetragen sind, und nicht verfolgte Dateien („untracked"), die dort noch nicht stehen.
Die .gitignore betrifft nur die zweite Gruppe. Sie ist eine Liste von Dateien, die nicht als Kandidaten für die Versionierung infrage kommen sollen – kein Befehl, der bereits verfolgte Dateien wieder freigibt.
Ein verbreiteter Ablauf führt daher zum Problem: Sie legen ein Projekt an, führen zuerst git add . aus und befüllen erst danach die .gitignore. Was in der Zwischenzeit in den Index gelangt ist – node_modules/, Build-Artefakte, lokale Konfigurationsdateien –, verschwindet auch mit passender Regel nicht wieder.
Deshalb zeigt sich das Problem oft erst spät. Verfolgte Dateien erscheinen in git status nur, wenn sich ihr Inhalt ändert. Sobald Sie eine einzige Zeile anpassen, taucht die Datei mit der Markierung M auf, und Sie fragen sich, warum sie trotz eindeutiger Regel nicht ignoriert wird.
Zwei Befehle, die die Ursache eingrenzen
Bevor Sie etwas reparieren, sollten Sie die Ursache klären. Ein Problem mit der Verfolgung und ein Problem mit dem Muster haben völlig unterschiedliche Lösungen.
Schritt 1: Prüfen, ob die Datei verfolgt wird
git ls-files --error-unmatch config.local
Wird der Pfad unverändert ausgegeben, wird die Datei verfolgt. Steht sie nicht im Index, erhalten Sie die Fehlermeldung did not match any file(s) known to git und den Exit-Code 1. Wenn Sie ein ganzes Verzeichnis prüfen möchten, genügt der Pfad allein, zum Beispiel git ls-files node_modules.
Schritt 2: Prüfen, ob die Regel den Pfad tatsächlich erfasst
git check-ignore -v --no-index config.local
Greift eine Regel, wird wie in .gitignore:1:config.local config.local ausgegeben, welches Muster in welcher Datei und in welcher Zeile den Pfad erfasst hat. Kommt keine Ausgabe und der Exit-Code ist 1, erfasst das Muster den Pfad nicht.
Entscheidend ist hier --no-index. Standardmäßig zeigt git check-ignore verfolgte Dateien gar nicht an. Ohne die Option erhalten Sie also eine leere Ausgabe, obwohl die Regel in Ordnung ist, und suchen an der falschen Stelle.
Aus beiden Ergebnissen zusammen ergibt sich die Antwort:
| Schritt 1 (Verfolgung) | Schritt 2 (Regel) | Ursache |
|---|---|---|
| Pfad wird ausgegeben | Regel greift | Problem mit der Verfolgung – mit git rm --cached (siehe unten) aufheben |
| Pfad wird ausgegeben | Regel greift nicht | Beides ist ein Problem – Muster korrigieren und Verfolgung aufheben |
| Fehler (nicht verfolgt) | Regel greift nicht | Problem mit dem Muster – Abschnitt zur Syntax prüfen |
Verfolgung beenden mit git rm --cached
Mit der Option --cached entfernt git rm eine Datei nur aus dem Index. Wie es in der offiziellen Dokumentation heißt, bleibt die Datei im Arbeitsverzeichnis unabhängig von ihrem Änderungsstatus unangetastet. Auf der Festplatte wird nichts gelöscht.
git rm --cached config.local # eine einzelne Datei
git rm -r --cached node_modules # ganzes Verzeichnis (-r = rekursiv)
git commit -m "chore: stop tracking ignored files"
Nach dem Ausführen ist der Status D (gelöscht) vorgemerkt und wird erst mit dem Commit wirksam. Danach greift die .gitignore-Regel für die Datei, und sie bleibt in git status unsichtbar.
Wenn Sie Ihre Regeln neu aufgesetzt haben und sie auf das gesamte Repository erneut anwenden möchten, committen Sie zuerst Ihre laufenden Änderungen. Danach können Sie den Index leeren und neu befüllen:
git rm -r --cached .
git add .
git status # Liste der zu löschenden Dateien unbedingt prüfen
git commit -m "chore: apply .gitignore"
Die in git status mit D angezeigten Einträge sind genau die Dateien, die künftig ignoriert werden. Steht dort eine Datei, die nicht entfernt werden darf, committen Sie nicht, sondern korrigieren zuerst die .gitignore.
Zwei Dinge sollten Sie beachten. Erstens: Dieser Vorgang beendet nur die künftige Verfolgung. In der bereits committeten Historie bleibt die Datei erhalten. Bei Werten wie Zugangsschlüsseln, die in einem gemeinsamen Repository gelandet sind, ist es deshalb am sichersten, den Schlüssel selbst neu auszustellen.
Zweitens: Wenn andere Personen pullen, kann die Datei in deren Arbeitsverzeichnis verschwinden. Handelt es sich um lokale Konfigurationsdateien, die jeder für sich anlegt, sollten Sie in der Commit-Nachricht oder per Hinweis im Team darauf aufmerksam machen, dass jeder sie neu erstellen muss.
Mit unserem Tool prüfen. Lag das Problem bei den Regeln, sollten Sie die .gitignore füllen, bevor Sie erneut committen. Wenn Sie Vorlagen wie Node, Python, macOS oder VSCode auswählen, werden die jeweiligen Standardregeln zu einer Datei zusammengeführt.
Ohne Installation und Registrierung: Die Vorlagen werden direkt im Browser zusammengeführt, Ihre Auswahl wird nicht an einen Server übertragen.

Muster-Syntax: Schrägstrich, ** und !
Lag das Problem beim Muster, lösen Sie es meistens mit nur drei Syntaxregeln. Alle folgenden Regeln stammen aus dem Abschnitt PATTERN FORMAT der offiziellen Git-Dokumentation.
Die Position des Schrägstrichs bestimmt den Geltungsbereich. Steht am Anfang oder in der Mitte eines Musters ein Schrägstrich, ist es ein relativer Pfad ab dem Ort der jeweiligen .gitignore. Fehlt er, wird in jeder beliebigen Tiefe darunter gesucht. Steht ein Schrägstrich am Ende, werden nur Verzeichnisse erfasst.
| Muster | Erfasst |
|---|---|
build/ | Ein Verzeichnis namens build in beliebiger Tiefe |
/build/ | Nur das Verzeichnis build an dem Ort, an dem die .gitignore liegt |
build | Dateien und Verzeichnisse mit dem Namen build |
**/foo | foo an jeder beliebigen Stelle (gleichbedeutend mit foo) |
abc/** | Alles innerhalb von abc, ohne Tiefenbegrenzung |
a/**/b | a/b, a/x/b, a/x/y/b … |
! macht zuvor Ausgeschlossenes wieder rückgängig. Es gibt allerdings eine Einschränkung, und sie ist die häufigste Falle: Wird ein übergeordnetes Verzeichnis komplett ausgeschlossen, lassen sich Dateien darin nicht wieder einschließen. Aus Performance-Gründen schaut Git nicht in ausgeschlossene Verzeichnisse hinein, deshalb bleibt ein Muster für eine Datei darin wirkungslos, egal wo Sie es platzieren.
.vscode/ # ✗ ganzer Ordner ausgeschlossen → das ! unten wirkt nicht
!.vscode/settings.json
.vscode/* # ✓ schließt nur die „Einträge darin" aus → das ! funktioniert
!.vscode/settings.json
Wenn Sie git check-ignore -v --no-index .vscode/settings.json tatsächlich ausführen, meldet die obere Variante die Regel .vscode/ als zutreffend, die untere dagegen !.vscode/settings.json. Sie sehen also direkt, welche Zeile sich durchgesetzt hat. Aus demselben Grund verwendet auch die VSCode-Vorlage in unserem Tool die Form .vscode/*.
Innerhalb derselben Datei gewinnt das zuletzt zutreffende Muster. Deshalb muss eine !-Ausnahme immer unterhalb der Ausschlussregel stehen. Ebenso überschreibt die .gitignore in einem Unterverzeichnis die Regeln des übergeordneten Verzeichnisses.
Typische Stolperstellen
| Situation | Was Sie prüfen sollten |
|---|---|
| Die Regel steht drin, aber die Datei wird trotzdem committet | Datei wird bereits getrackt – git rm --cached |
check-ignore gibt nichts aus | Haben Sie --no-index vergessen? |
Eine !-Ausnahme greift nicht | Wurde das übergeordnete Verzeichnis komplett ausgeschlossen? |
| Eine Datei wird ignoriert, obwohl Sie dafür keine Regel geschrieben haben | .git/info/exclude des Repositorys, globales core.excludesFile |
| Muster mit Leerzeichen am Zeilenende | Nachgestellte Leerzeichen werden ignoriert (mit einem Backslash statt mit Anführungszeichen schützen) |
Dateiname beginnt mit # oder ! | Ein Backslash vor dem ersten Zeichen sorgt dafür, dass es wörtlich behandelt wird |
Die letzten beiden Zeilen sorgen manchmal für Verwirrung. Eine Zeile, die mit # beginnt, ist ein Kommentar, und eine Zeile, die mit ! beginnt, ist eine Negation. Wenn Sie eine Datei ignorieren möchten, deren Name tatsächlich mit einem dieser Zeichen beginnt, setzen Sie einen Backslash vor das erste Zeichen, zum Beispiel \#temp.
Auch der umgekehrte Fall – „Die Datei wird ignoriert, obwohl ich nie eine Regel dafür geschrieben habe" – lässt sich mit demselben Befehl klären. In der Ausgabe von git check-ignore -v --no-index steht in der ersten Spalte der Pfad der Datei, aus der die Regel stammt. So erkennen Sie sofort, ob die Regel aus der globalen Konfiguration oder aus dem Repository kommt. Den Speicherort der globalen Datei zeigt git config --get core.excludesFile an.
Zusammenfassung
.gitignoregilt nur für Dateien, die noch nicht getrackt werden. Auf bereits getrackte Dateien hat es keine Wirkung.- Ob eine Datei getrackt wird, prüfen Sie mit
git ls-files --error-unmatch <Pfad>, ob eine Regel greift, getrennt davon mitgit check-ignore -v --no-index <Pfad>. - Das Tracking beenden Sie mit
git rm --cached(bei Ordnern mit zusätzlichem-r). Die Dateien im Arbeitsverzeichnis werden dabei nicht gelöscht. Wirksam wird die Änderung erst nach einem Commit. - Damit beenden Sie nur das künftige Tracking. In der bisherigen Historie bleibt die Datei erhalten. Wenn Zugangsdaten offengelegt wurden, ist es daher am sichersten, sie neu auszustellen.
- Die Position eines Schrägstrichs bestimmt den Geltungsbereich eines Musters, ein Schrägstrich am Ende beschränkt es auf Verzeichnisse.
- Eine
!-Ausnahme funktioniert nicht, wenn das übergeordnete Verzeichnis komplett ausgeschlossen ist. Verwenden Sie.vscode/*statt.vscode/.
Ohne Installation und Registrierung: Die Vorlagen werden direkt im Browser zusammengeführt, Ihre Auswahl wird nicht an einen Server übertragen.
Häufig gestellte Fragen
Wird die Datei bei git rm --cached wirklich gelöscht?
Nein. Laut der offiziellen Dokumentation entfernt diese Option den Pfad nur aus dem Index. Die Datei im Arbeitsverzeichnis bleibt unabhängig davon, ob sie geändert wurde, unverändert bestehen.
Die Datei bleibt also auf der Festplatte, Git verfolgt sie nach dem Commit lediglich nicht mehr. Allerdings kann die Datei im Arbeitsverzeichnis anderer Personen verschwinden, wenn diese den Commit mit der Löschung übernehmen.
Verschwindet eine bereits committete Konfigurationsdatei aus der Historie, wenn ich sie jetzt ignoriere?
Nein. Ein neuer .gitignore-Eintrag und git rm --cached beenden nur das künftige Tracking. In früheren Commits bleibt der Inhalt unverändert erhalten, sodass jeder, der das Repository klont, die Datei aus der Historie abrufen kann.
Um die Historie selbst zu bereinigen, müssen Sie Commits umschreiben. Das ist ein gesonderter Vorgang und hat in der Zusammenarbeit mit anderen große Auswirkungen. Wenn Werte wie Zugangsschlüssel offengelegt wurden, ist es die sicherste Maßnahme, die Werte neu auszustellen, bevor Sie an der Historie etwas ändern.
Wird auch eine .gitignore in einem Unterordner berücksichtigt?
Ja. Git prüft die .gitignore-Dateien des Verzeichnisses, in dem der Pfad liegt, und die aller übergeordneten Verzeichnisse. Regeln aus tieferen Dateien überschreiben die Regeln aus höheren.
Danach folgen die repositoryspezifische Datei .git/info/exclude und zuletzt die globale Datei, die über core.excludesFile festgelegt ist. Welche Zeile in welcher Datei den Ausschlag gegeben hat, sehen Sie in der Ausgabe von git check-ignore -v --no-index.
Werden die im Generator gewählten Einträge an einen Server gesendet?
Nein. Die Vorlagen sind direkt in die Seite eingebunden, sodass Auswählen, Kombinieren und Kopieren vollständig im Browser ablaufen. Wenn Sie mehrere Vorlagen gemeinsam auswählen, entstehen überlappende Zeilen wie build/. Ist die Option „Doppelte Zeilen entfernen" aktiviert, bleibt jede Zeile nur einmal erhalten.
Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen