git mv

Der Befehl git mv verschiebt oder benennt eine Datei oder ein Verzeichnis um, das Git bereits verfolgt, und stagt die Änderung in einem einzigen Schritt. Dieses Kapitel erklärt, wie man eine Datei umbenennt, eine Datei in ein Verzeichnis verschiebt, die Optionen, die man tatsächlich verwendet (-f, -n, -k), sowie mögliche Fallstricke — insbesondere dass git mv nur bei Dateien funktioniert, die Git bereits kennt, und dass Git Umbenennungen nicht als Datensätze speichert.

Definition

git mv ist ein praktischer Hilfsbefeh. Das Ausführen entspricht dem manuellen Verschieben der Datei, dem Melden des alten Pfads mit git rm und dem Hinzufügen des neuen Pfads mit git add — alles auf einmal. Der Vorteil ist, dass der Arbeitsbereich und der Staging-Bereich nie — auch nicht für einen Moment — auseinanderfallen.

Eine Datei umbenennen

Um eine verfolgte Datei umzubenennen, geben Sie den alten und den neuen Namen an:

git mv old-name.txt new-name.txt

Die Datei wird auf dem Datenträger umbenannt und die Änderung ist bereits gestagt und bereit zum Committen. Ein anschließendes git status zeigt einen sauberen Umbenennungseintrag. Die Kurzform macht das deutlich — das R-Flag markiert eine gestagte Umbenennung:

git status --short

R  old-name.txt -> new-name.txt

Es bleibt nur noch, die Änderung mit git commit zu committen.

Eine Datei in ein Verzeichnis verschieben

Geben Sie ein Verzeichnis als Ziel an, um eine Datei zu verschieben, ohne sie umzubenennen:

git mv styles.css assets/

Sie können mehrere Dateien in einem Befehl in ein Verzeichnis verschieben, solange das Ziel ein vorhandener Ordner ist:

git mv main.css reset.css print.css assets/

Wenn das letzte Argument ein vorhandenes Verzeichnis ist, wird jeder vorherige Pfad dorthin verschoben. Wenn das Verzeichnis noch nicht existiert, behandelt Git das letzte Argument als neuen Dateinamen — erstellen Sie den Ordner daher zunächst mit mkdir, wenn Sie Dateien darin verschieben möchten.

Ein Verzeichnis umbenennen

Übergeben Sie ein verfolgtes Verzeichnis als Quelle, um es zusammen mit allem darin zu verschieben oder umzubenennen:

git mv src/ lib/

Git stagt für jede verfolgte Datei im Verzeichnis eine Umbenennung, sodass ein einzelnes git mv viele renamed:-Einträge in git status erzeugen kann.

Was git mv Ihnen erspart

Ohne git mv erfordert dieselbe Umbenennung drei manuelle Schritte:

mv old-name.txt new-name.txt
git rm old-name.txt
git add new-name.txt

git mv fasst diese zu einem einzigen Schritt zusammen und stellt sicher, dass der Staging-Bereich konsistent bleibt. Beachten Sie, dass Git Umbenennungen nicht tatsächlich speichert — es erkennt sie durch Vergleich des Dateiinhalts, wenn Sie git log oder git diff ausführen. git mv sorgt lediglich dafür, dass die Änderung im Arbeitsbereich ordentlich und vorab gestagt ist.

git mv funktioniert nur mit verfolgten Dateien

git mv arbeitet mit Dateien, die Git bereits verfolgt. Das Anwenden auf eine nicht verfolgte Datei schlägt fehl:

git mv note.txt moved.txt

fatal: not under version control, source=note.txt, destination=moved.txt

Für eine Datei, die Git noch nie gesehen hat, benennen Sie sie einfach mit dem normalen Shell-Befehl mv um und stagen Sie den neuen Namen dann mit git add. Verwenden Sie git mv, sobald die Datei committet wurde.

Häufige Optionen

Wenn das Ziel bereits existiert

Standardmäßig lehnt Git es ab, eine vorhandene Datei zu überschreiben. Wenn Sie sie ersetzen möchten, fügen Sie das Force-Flag hinzu:

git mv -f draft.md final.md

Verwenden Sie dies vorsichtig, da dadurch der bisherige Inhalt des Ziels verworfen wird.

Vorschau mit einem Probelauf

Vor einer umfangreichen Verschiebung verwenden Sie -n (oder --dry-run), um genau zu sehen, was Git tun würde — es wird nichts umbenannt und nichts gestagt:

git mv -n old-name.txt new-name.txt

Checking rename of 'old-name.txt' to 'new-name.txt'
Renaming old-name.txt to new-name.txt

Kombinieren Sie dies mit -v (verbose), um jede Umbenennung während einer echten Verschiebung auszugeben.

Verwandte Befehle

• git rm — verfolgte Dateien entfernen; git mv führt intern ein rm des alten Pfads durch.
• git add — Änderungen stagen; git mv führt das entsprechende add des neuen Pfads für Sie aus.
• git status — die gestagte Umbenennung vor dem Committen bestätigen.
• git commit — die Verschiebung in der Historie festhalten.
• git log — Umbenennungen mit git log --follow <file> anzeigen, um die Historie einer Datei über Verschiebungen hinweg zu verfolgen.

Übung