git filter-branch

Patches & Umschreiben

Schreibt die Historie mit Filtern um (veraltet — nutze git filter-repo)

Der Befehl 'git filter-branch' schreibt jeden Commit eines Branches durch Filter um — etwa, um eine Datei aus der gesamten Historie zu entfernen. Er ist langsam, leicht falsch zu benutzen und offiziell nicht empfohlen: Git selbst gibt eine Warnung aus und empfiehlt git filter-repo. Wie jedes Umschreiben gibt er jedem Commit einen neuen Hash, also müssen alle neu klonen oder zurücksetzen.

Syntax

git filter-branch [--index-filter <cmd>] [--tree-filter <cmd>] [--msg-filter <cmd>] [--] <rev-list>
[ ] optional| oder<arg> Platzhalter... wiederholbar--flag Option

Beispiele

Eine Datei überall entfernen

git filter-branch --index-filter 'git rm --cached --ignore-unmatch .env' HEAD

Der alte, langsame Weg.

Der empfohlene Weg

git filter-repo --path .env --invert-paths

git filter-repo (separates Werkzeug) erledigt das schnell und sicher.

Workflow-Beispiele

1
Rotate the secret

Zuerst unbrauchbar machen

2
git filter-repo --path config/secret.yml --invert-paths

Aus der Historie entfernen

3
git push --force --all

Die Remote-Historie ersetzen

Fehlerbehebung

Neues Backup kann nicht angelegt werden

Ursache: refs/original existiert von einem früheren Lauf

Lösche es (git update-ref -d refs/original/refs/heads/main) oder nutze -f

Tipps & Stolperfallen

Best Practices

  • ✓Nutze stattdessen git filter-repo.
  • ✓Sichere das Repository vor jedem Umschreiben.

Häufige Fehler

  • ✗Geteilte Historie umschreiben, ohne das Team zu informieren.
  • ✗Glauben, ein Umschreiben mache ein geleaktes Geheimnis sicher — tausche das Geheimnis aus.

FAQ

A:

Er ist sehr langsam und hat viele Fallstricke, die das Umschreiben stillschweigend verderben; filter-repo behebt beides.