Dateien umbenennen in Git, ohne die Historie zu begraben

Kennst du diesen Moment, wenn du eine Datei umbenennst, danach git log aufrufst – und nichts. Leere. Die komplette Geschichte weg, als hätte die Datei gerade erst angefangen zu existieren?

Das ist kein Bug. Das ist Git, das genau das macht, was du ihm gesagt hast. Und mit einem kleinen Trick lässt sich das ganz einfach vermeiden.

Warum mv in Git ein Problem ist

Stell dir vor, du arbeitest seit Wochen an user_helper.py. Hundert Commits, Bugfixes, Refactorings – eine ehrliche Geschichte. Dann entscheidest du dich, die Datei in auth_utils.py umzubenennen, weil der Name einfach besser passt.

Du tippst:

mv user_helper.py auth_utils.py
git add .
git commit -m "rename user_helper to auth_utils"

Alles gut, oder? Nicht wirklich. Wenn du jetzt git log auth_utils.py aufrufst, siehst du genau einen Commit: den Rename-Commit. Die Vergangenheit ist weg – zumindest auf den ersten Blick.

Das liegt daran, wie Git intern funktioniert. Git trackt keine Dateien, sondern den Inhalt. Es speichert Snapshots, keine Diffs. Wenn du eine Datei löschst und eine neue anlegst, sieht Git: alte Datei weg, neue Datei da. Kein automatischer Zusammenhang.

Die einfache Lösung: git mv

Der einfachste Fix ist, statt mv direkt git mv zu benutzen:

git mv user_helper.py auth_utils.py
git commit -m "rename user_helper to auth_utils"

Was passiert hier anders? git mv markiert die Operation explizit als Rename im Index. Git weiß dann beim Commit: das ist keine neue Datei, das ist dieselbe Datei unter anderem Namen.

Intern macht git mv übrigens nichts Magisches – es führt mv, git rm und git add in einem Schritt aus. Aber das Staging ist entscheidend: Git erkennt den Rename und speichert ihn als solchen.

Was, wenn du es vergessen hast?

Kein Grund zur Panik. Git ist tatsächlich ziemlich schlau, was Renames angeht. Auch wenn du mv benutzt hast, versucht Git beim Anzeigen der History automatisch, Renames zu erkennen – basierend auf der Ähnlichkeit des Inhalts.

Der Trick ist das --follow-Flag:

git log --follow auth_utils.py

Mit --follow schaut Git über Renames hinweg und zeigt dir die komplette Geschichte der Datei – auch bevor sie umbenannt wurde. Das funktioniert gut, solange du nicht gleichzeitig 80 % des Inhalts geändert hast.

Wie gut die Rename-Erkennung funktioniert, hängt vom Similarity-Threshold ab. Standard sind 50 % – Git nimmt an, dass es sich um einen Rename handelt, wenn mindestens die Hälfte des Inhalts übereinstimmt. Den Wert kannst du mit -M anpassen:

git log --follow -M80 auth_utils.py

Das sagt Git: nur als Rename zählen, wenn mindestens 80 % identisch sind. Nützlich bei großen Umstrukturierungen.

Renames bei git diff sichtbar machen

Auch git diff hat einen ähnlichen Schalter. Wenn du sehen willst, ob Git einen Rename erkannt hat:

git diff --stat -M HEAD~1

In der Ausgabe siehst du dann sowas wie:

user_helper.py => auth_utils.py | 0

Das 0 bedeutet: kein Inhalt hat sich geändert, nur der Name. Perfekt.

Mehrere Dateien auf einmal umbenennen

Manchmal willst du nicht nur eine Datei umbenennen, sondern gleich ein ganzes Verzeichnis umstrukturieren. Hier hilft eine Kombination aus Shell und Git:

# Verzeichnis umbenennen
git mv helpers/ utils/

# Oder mit find für selektives Umbenennen
find . -name "*_helper.py" | while read f; do
  git mv "$f" "${f/_helper/_utils}"
done

Das Staging passiert automatisch mit jedem git mv, du musst nur noch committen.

Das Rename in der Commit-Message erwähnen

Kleiner Tipp noch für die Zusammenarbeit im Team: Schreib in die Commit-Message dazu, was und warum du umbenannt hast. Nicht nur wegen der Dokumentation – auch weil Tools wie GitHub oder GitLab Renames manchmal unterschiedlich darstellen und deine Teamkollegen froh sind, wenn sie wissen, was passiert ist.

rename: user_helper → auth_utils

Besseres Naming nach der Auth-Refactoring-Session.
Inhalt unverändert.

Kurz zusammengefasst

Wenn du in Git Dateien umbenennst:

• Benutze git mv statt mv, damit der Rename im Index landet
• Falls du mv benutzt hast: git log --follow zeigt trotzdem die vollständige History
• Mit -M kannst du den Similarity-Threshold für die Rename-Erkennung anpassen
• git diff --stat -M zeigt dir, ob Git den Rename erkannt hat

Die Geschichte deines Codes ist es wert, sie zu bewahren. Mit git mv und --follow passiert das fast von selbst.

Vorschaubild: Erda Estremera, Unsplash