git checkout, switch und restore: Was wann verwenden?

Warum git checkout zwei Rollen hat

git checkout erledigt historisch zwei grundverschiedene Operationen. Mit einem Branch-Namen wechselt es HEAD und aktualisiert das Arbeitsverzeichnis. Mit einem Dateipfad holt es die Version der Datei aus dem Index oder einem Commit und überschreibt stillschweigend Ihre Änderungen. Derselbe Befehl wechselt also mal gefahrlos zwischen Branches und verwirft mal unwiderruflich ungesicherte Arbeit.

Deshalb kamen mit Git 2.23 zwei eigene Befehle hinzu: git switch für Branches und git restore für Dateien. Checkout wurde nicht entfernt und funktioniert vollständig, aber in neuem Code, in der Dokumentation und in den Hinweisen von Git selbst werden switch und restore verwendet. Wenn Sie gerade lernen, beginnen Sie mit ihnen; checkout sollten Sie trotzdem kennen — es taucht in Anleitungen, Skripten und Vorstellungsgesprächen auf.

Gegenüberstellung der Befehle

Beachten Sie das -- in den checkout-Befehlen. Es ist ein Trenner für „ab hier folgen Pfade“ und verhindert Mehrdeutigkeit, wenn eine Datei und ein Branch gleich heißen. Bei restore gibt es dieses Problem nicht, weil der Befehl nur mit Dateien arbeitet.

git checkout für Branches

git checkout feature/login        # wechseln
git checkout -b feature/login     # vom aktuellen Commit erstellen und wechseln
git checkout -b hotfix origin/main   # von einem Remote-Branch erstellen
git checkout -t origin/feature/x  # lokaler Branch, der einem Remote-Branch folgt

Gibt es keinen lokalen Branch, aber auf dem Server einen mit diesem Namen, legt git checkout feature/x (genau wie git switch feature/x) selbst einen lokalen Branch an und richtet das Tracking ein. Vorher ist git fetch nötig, sonst kennt Git den neuen Remote-Branch nicht.

Beim Wechseln gehen nicht committete Änderungen nicht verloren: Sie werden in den anderen Branch mitgenommen, sofern sie nicht mit ihm kollidieren. Bei einem Konflikt verweigert Git und schlägt vor, die Änderungen zu committen oder mit git stash zwischenzuspeichern. Das Flag -f (--force) wechselt den Branch und verwirft lokale Änderungen — das ist bereits eine gefährliche Operation.

git switch: nur Branches

Switch übernimmt den Branch-Teil von checkout, aber mit strengeren Regeln. Der wichtigste Unterschied: Ohne explizites --detach wechselt es nicht zu einem Commit oder Tag. git switch v1.0 meldet einen Fehler, statt unbemerkt in den detached HEAD zu wechseln — versehentlich „außerhalb eines Branches“ zu landen wird dadurch schwerer.

git switch main
git switch -c feature/cart
git switch -c feature/cart origin/main
git switch --detach v1.0
git switch -              # vorheriger Branch
git switch -m main        # Änderungen per Three-Way-Merge mitnehmen

git restore: der Rückgängig-Knopf für Dateien

Restore setzt Dateien auf einen gespeicherten Stand zurück und lässt die Commit-Historie unangetastet. Um es sicher zu nutzen, sollten Sie die drei Bereiche von Git im Kopf haben: das Arbeitsverzeichnis (was Sie im Editor sehen), den Index (was mit git add vorgemerkt ist) und die Commits.

Änderungen an einer Datei vor git add verwerfen

git restore app.js         # Version aus dem Index wiederherstellen
git restore src/           # alle Dateien im Ordner
git restore .              # alle geänderten Dateien im Projekt

Ohne Flags stellt restore das Arbeitsverzeichnis aus dem Index wieder her. Wurde die Datei seit dem letzten Commit nicht zum Index hinzugefügt, entspricht das der Version aus dem letzten Commit. Die Änderungen verschwinden spurlos, sie landen in keinem Papierkorb — werfen Sie daher vor git restore . einen Blick auf git diff.

Datei nach git add aus dem Index nehmen

git restore --staged app.js

Die Datei ist nicht mehr für den Commit vorgemerkt, Ihre Änderungen darin bleiben aber erhalten. Das ist die sicherste Form von restore: Nichts geht verloren. Genau diesen Befehl schlägt git status im Abschnitt „Changes to be committed“ vor.

Alles verwerfen: im Index und in der Datei

git restore --staged --worktree app.js
# Kurzform
git restore -SW app.js

Datei aus einem anderen Commit oder Branch holen

git restore --source=HEAD~2 app.js          # Version von vor zwei Commits
git restore --source=main config.yml        # Version aus dem Branch main
git restore --source=3f2a1c9 -- docs/       # ganzer Ordner aus einem Commit

Standardmäßig ändert --source nur das Arbeitsverzeichnis. Ergänzen Sie --staged, wenn die Änderung gleich für den Commit vorgemerkt werden soll. Die alte Variante git checkout main -- app.js ändert immer sowohl Index als auch Arbeitsverzeichnis.

Gelöschte Datei wiederherstellen

git restore deleted.txt                          # gelöscht, aber noch nicht committet
git restore --source=HEAD~1 deleted.txt          # Löschung bereits committet

Wissen Sie nicht, in welchem Commit die Datei gelöscht wurde, finden Sie es so heraus: git log --oneline -- deleted.txt. Der oberste Commit in der Liste ist der, in dem die Datei gelöscht wurde; wiederherstellen müssen Sie sie aus dessen Elternteil: git restore --source=<hash>~1 deleted.txt.

restore, reset und revert: nicht verwechseln

Alle drei Befehle „machen rückgängig“, aber auf unterschiedlicher Ebene:

• restore — arbeitet mit Dateien im Arbeitsverzeichnis und im Index, ändert die Historie nicht. Unbedenklich fürs Team.
• reset — verschiebt den Branch-Zeiger zurück und schreibt die Historie um. --soft behält die Änderungen im Index, --mixed (Standard) im Arbeitsverzeichnis, --hard löscht sie. Für bereits gepushte Commits in gemeinsamen Branches gefährlich.
• revert — erstellt einen neuen Commit, der den angegebenen umkehrt. Die Historie wird nicht umgeschrieben, deshalb ist das der richtige Weg, einen Commit rückgängig zu machen, der schon auf dem Server liegt.

Einfache Regel: Änderungen noch nicht committet — restore; Commit nur lokal — reset; Commit schon bei Kollegen — revert.

Detached HEAD nach checkout

Nach git checkout 3f2a1c9 oder git checkout v1.0 sehen Sie eine lange Warnung „You are in 'detached HEAD' state“. HEAD zeigt jetzt auf einen Commit statt auf einen Branch. Das ist praktisch, um eine alte Version anzusehen oder Tests darauf laufen zu lassen.

Committen ist in diesem Zustand möglich, aber neue Commits landen in keinem Branch. Wenn Sie etwas geändert haben und es behalten wollen:

git switch -c fix-for-v1

Haben Sie nur geschaut, kehren Sie zurück: git switch - oder git switch main. Sind Sie weggewechselt, ohne einen Branch anzulegen, sind die Commits noch über git reflog erreichbar: Suchen Sie den Hash und führen Sie git branch rescue <hash> aus.

Typische Fehler

error: pathspec 'feature' did not match any file(s) known to git

Git hat weder einen Branch noch eine Datei mit diesem Namen gefunden. Meist existiert der Branch nur auf dem Server, und es wurde kein fetch ausgeführt. Führen Sie git fetch aus und versuchen Sie es erneut. Prüfen Sie auch die Schreibweise: Branch-Namen unterscheiden Groß- und Kleinschreibung.

Änderungen versehentlich mit checkout -- oder restore verworfen

Nicht committete Änderungen, die nicht im Index waren, speichert Git nicht, und mit Git-Mitteln lassen sie sich nicht zurückholen. Bleibt nur der lokale Verlauf Ihres Editors oder Ihrer IDE. Wurde die Datei dagegen mit git add hinzugefügt, liegt ihr Inhalt als „hängendes“ Objekt in der Datenbank und lässt sich mit git fsck --lost-found finden.

Datei und Branch mit gleichem Namen

git checkout test gibt eine Warnung wegen Mehrdeutigkeit aus, wenn es einen Branch test und einen Ordner test gibt. Verwenden Sie git switch test für den Branch und git restore test (oder git checkout -- test) für Dateien.

Alltägliche Arbeitsszenarien

Einige Situationen, die ständig vorkommen, und der passende Befehl für jede:

• Sie haben angefangen, eine Datei zu bearbeiten, und merken, dass Sie auf dem Holzweg sind — git restore datei.
• Vor dem Commit eine überflüssige Datei zum Index hinzugefügt — git restore --staged datei.
• Mitten in der Arbeit dringend zu einer anderen Aufgabe wechseln — git stash, dann git switch branch; zurück mit git switch - und git stash pop.
• Eine einzelne Datei aus einem anderen Branch übernehmen, ohne den ganzen Branch zu mergen — git restore --source=feature/x --staged --worktree pfad.
• Prüfen, ob ein Bug schon in der vorigen Version auftrat — git switch --detach v1.0, testen, dann git switch -.
• Nur einen Teil der Änderungen in einer Datei zurücknehmen — git restore -p datei: Git zeigt jedes Fragment und fragt, ob es verworfen werden soll.

Der interaktive Modus -p (--patch) ist besonders nützlich: Es gibt ihn bei checkout und restore, und er erlaubt, Debug-Ausgaben zu entfernen und gleichzeitig sinnvolle Änderungen in derselben Datei zu behalten.

Ergebnis vor dem Verwerfen prüfen

Restore und checkout mit Pfaden verwerfen Änderungen ohne Rückfrage, deshalb lohnt sich ein Blick darauf, was genau verloren geht. git diff zeigt Änderungen im Arbeitsverzeichnis gegenüber dem Index, git diff --staged das für den Commit Vorgemerkte, git diff main -- app.js den Unterschied zur Version in einem anderen Branch. Im Zweifel sichern Sie den aktuellen Stand mit git stash: Von dort lassen sich Änderungen im Gegensatz zu restore immer zurückholen.

Fazit

git checkout vereint Branch-Wechsel und Dateiwiederherstellung, und genau das macht es gefährlich. Nutzen Sie für Branches git switch und für Dateien git restore: Der eine Befehl ändert nur die Position von HEAD, der andere nur den Inhalt von Dateien. Branches, restore, reset und revert mit guten und schlechten Szenarien werden im Git-Kurs praktisch behandelt.