Übersicht

git filter-repo --path <path> [--invert-paths]
git filter-repo --replace-text <file>
git filter-repo --strip-blobs-bigger-than 10M

Beschreibung

Das git filter-repo-Tool ist die moderne, empfohlene Methode, Git-Historie umzuschreiben. Es ersetzt das veraltete git filter-branch, das langsam und fehleranfällig ist. filter-repo kann große Dateien entfernen, sensible Daten beseitigen (versehentlich committete Credentials), Pfade umstrukturieren, Autoren über eine Mailmap umschreiben oder Unterverzeichnisse in eigene Repositories extrahieren.

Es wird separat vom Kern-Git verteilt (typischerweise via pip install git-filter-repo oder Ihrem Paketmanager). Operationen sind destruktiv — arbeiten Sie immer auf einem frischen Klon und stimmen Sie sich mit Mitwirkenden ab, weil sich jeder SHA ändert.

Im täglichen Einsatz integriert sich git filter-repo eng mit Shell-Aliasen, Editor-Plugins und Continuous Integration. Power-User fügen oft Aliase hinzu, die Flags kombinieren, die sie immer übergeben, oder wickeln den Befehl in Skripte, die Teamkonventionen durchsetzen. Die Ausgabeformatierung kann über Git-Config angepasst werden — Pretty-Formate, Farbschemata und Pager-Verhalten sind alle einstellbar. Wenn etwas schiefgeht, ist der erste Diagnoseschritt üblicherweise, den Befehl erneut mit GIT_TRACE=1 in der Umgebung auszuführen, was die zugrunde liegenden Plumbing-Aufrufe offenlegt. Für ungewöhnliche Situationen öffnet die --help-Ausgabe (git filter-repo --help) die vollständige Manpage mit Details zu jeder Option, einschließlich solcher, die in alltäglichen Workflows selten verwendet werden, aber für Debugging oder Skripting im großen Maßstab essentiell sind.

Zu verstehen, wie git filter-repo mit dem Rest von Gits Datenmodell interagiert — der Objektdatenbank, dem Index, Refs und dem Working Tree — zahlt sich aus. Jeder Befehl operiert auf einer Teilmenge dieser Stücke, und zu wissen, welche er berührt, hilft Ergebnisse vorherzusagen und sich von Fehlern zu erholen. Das Lesen der offiziellen Git-Dokumentation neben praktischer Übung in einem Wegwerf-Repository ist der schnellste Weg, die Nuancen zu verinnerlichen. Die meisten Produktionsprobleme mit Git rühren von einer von drei Ursachen: überraschendem Standardverhalten, partiellen Netzwerkoperationen oder dem Umschreiben bereits geteilter Historie. Ein funktionierendes mentales Modell der Nebenwirkungen von git filter-repo hilft, alle drei zu vermeiden.

Häufige Optionen

Option	Beschreibung
--path <p>	Behält nur den angegebenen Pfad.
--invert-paths	Inverse: entfernt die angegebenen Pfade.
--path-glob <g>	Verwendet ein Glob-Muster.
--replace-text <file>	Ersetzt Strings in der gesamten Historie.
--strip-blobs-bigger-than <size>	Verwirft große Blobs.
--mailmap <file>	Schreibt Autor/Committer-Info um.
--analyze	Erzeugt einen Bericht zur Repo-Größe vor dem Umschreiben.
--force	Überschreibt die Frisch-Klon-Sicherheitsprüfung.

Beispiele

git filter-repo --analyze
    # Inspizieren, was Platz frisst

    git filter-repo --path docs/ --invert-paths
    # docs/ aus der gesamten Historie entfernen

    git filter-repo --strip-blobs-bigger-than 50M
    # Jede Datei über 50 MB entfernen

    echo 'API_KEY==>REDACTED' > replacements.txt
    git filter-repo --replace-text replacements.txt
    # Ein geleaktes Geheimnis bereinigen

Häufige Fehler

filter-repo in Ihrem Live-Repo ohne Backup auszuführen riskiert Datenverlust. Klonen Sie immer frisch. Nach dem Umschreiben force-pushen und Mitwirkende neu klonen lassen — jeder mit alten SHAs bekommt Konflikte. Das Tool entfernt standardmäßig origin, um versehentliche Pushes zu verhindern; fügen Sie ihn bewusst wieder hinzu.

Verwandte Befehle

git filter-branch (deprecated), git gc, git reflog, git push --force-with-lease