Übersicht

git mv [-f] [-k] [-n] <source> <destination>

Beschreibung

Der git mv-Befehl benennt eine verfolgte Datei um oder verschiebt sie und staget die Änderung. Intern entspricht er dem Ausführen von mv, gefolgt von git add auf den neuen Pfad und git rm auf den alten. Der Vorteil ist, dass die Umbenennung in einem einzigen atomaren Schritt geschieht, der eindeutig gestaged wird.

Hinweis: Git speichert Umbenennungen tatsächlich nicht als erstklassige Operationen. Stattdessen erkennt es Umbenennungen, indem es die Inhaltsähnlichkeit von Dateien zur Diff- und Log-Zeit vergleicht. Egal also, ob Sie git mv oder einfaches mv + git add + git rm verwenden, der resultierende Commit ist identisch, und die Umbenennungserkennung funktioniert genauso.

Im täglichen Einsatz integriert sich git mv 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 mv --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 mv 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 mv hilft, alle drei zu vermeiden.

Häufige Optionen

Option	Beschreibung
-f, --force	Überschreibt das Ziel, falls es existiert.
-k	Überspringt Verschiebe-/Umbenennungsaktionen, die fehlschlagen würden, ohne Fehler.
-n, --dry-run	Zeigt, was passieren würde, ohne es zu tun.
-v, --verbose	Meldet die Namen verschobener Dateien.

Beispiele

git mv old-name.txt new-name.txt
    # Eine Datei in einem Schritt umbenennen

    git mv src/utils.js src/lib/utils.js
    # Eine Datei in ein neues Verzeichnis verschieben (es muss bereits existieren)

    git mv -n *.md docs/
    # Vorschau auf das Verschieben aller Markdown-Dateien nach docs/

    git mv -f draft.md final.md
    # Überschreiben erzwingen, falls final.md bereits existiert

Häufige Fehler

Wenn Sie eine Datei außerhalb von Git umbenennen (mit Ihrem Editor oder mv), funktioniert Gits Umbenennungserkennung beim Diff üblicherweise immer noch — Sie müssen aber git add -A ausführen, um sowohl die Löschung als auch das Hinzufügen zu stagen. Ein weiteres Problem: reine Groß-/Kleinschreibungs-Umbenennungen auf Case-insensitiven Dateisystemen (macOS, Windows) erfordern git mv -f oder eine zweistufige Umbenennung über einen temporären Namen.

Verwandte Befehle

git add, git rm, git log --follow