Remote-Branch auschecken in Git: mit switch und checkout

Ein Kollege hat einen Branch auf GitHub gepusht, Sie sollen ihn lokal testen – aber git checkout feature-x bringt nur error: pathspec 'feature-x' did not match. Der Branch existiert, nur nicht in Ihrem lokalen Repository. Sie brauchen genau zwei Befehle: git fetch holt die Referenz vom Server, git switch feature-x legt daraus einen lokalen Branch an und wechselt hinein. Die Feinheiten – der Unterschied zwischen git switch und git checkout, mehrere Remotes und der gefürchtete „detached HEAD” – stehen weiter unten.

Der schnelle Weg (Git 2.23 und neuer)

Seit Git 2.23 (August 2019) gibt es dafür einen eigenen Befehl: git switch. Zwei Schritte reichen:

git fetch origin
git switch feature-x

git fetch holt die aktuellen Referenzen vom Remote, ohne Ihren Arbeitsstand zu verändern. Anschließend erkennt git switch feature-x, dass es lokal keinen Branch dieses Namens gibt, aber genau einen passenden Remote-Tracking-Branch (origin/feature-x). Git legt daraufhin automatisch einen lokalen Branch feature-x an, verbindet ihn als Upstream mit origin/feature-x und wechselt hinein. Diese Automatik nennt sich „DWIM” (Do What I Mean) und wird über die Konfiguration checkout.guess gesteuert (Standard: aktiviert). Ist sie deaktiviert – etwa durch eine restriktive Firmenkonfiguration –, bleibt nur der explizite Weg mit -c, wie im nächsten Abschnitt beschrieben.

Sie erkennen den Erfolg an der Ausgabe:

branch 'feature-x' set up to track 'origin/feature-x'.
Switched to a new branch 'feature-x'

Der Upstream-Bezug ist der eigentliche Gewinn: Ab jetzt genügen git pull und git push ohne weitere Argumente, weil Git weiß, gegen welchen Remote-Branch dieser lokale Branch arbeitet.

Der klassische Weg mit git checkout

git checkout funktioniert weiterhin und verhält sich bei Branch-Namen identisch:

git fetch origin
git checkout feature-x

Auch hier greift die DWIM-Automatik und erzeugt den Tracking-Branch. git switch wurde eingeführt, weil checkout historisch zu viele Aufgaben auf einmal übernimmt – Branches wechseln, Dateien zurücksetzen, Commits auschecken. Für neue Workflows ist switch die klarere Wahl; in bestehenden Skripten und Anleitungen begegnet Ihnen aber weiterhin checkout.

Wenn Sie den lokalen Branch anders benennen wollen als den Remote-Branch, geben Sie den Startpunkt explizit an:

git switch -c mein-lokaler-name origin/feature-x
# oder klassisch:
git checkout -b mein-lokaler-name origin/feature-x

Die Variante aus vielen älteren Tutorials – git checkout -b feature-x origin/feature-x mit identischem Namen – ist damit unnötig ausführlich. Sie ist nicht falsch, aber git switch feature-x erledigt dasselbe kürzer.

Welche Remote-Branches gibt es überhaupt?

Bevor Sie auschecken, verschaffen Sie sich einen Überblick. git fetch aktualisiert die Referenzen, zeigt sie aber nicht auf. Dafür gibt es git branch:

git branch -r        # nur Remote-Tracking-Branches
git branch -a        # lokale und Remote-Branches zusammen

Die Ausgabe listet Einträge wie origin/main, origin/develop, origin/feature-x. Der Eintrag origin/HEAD -> origin/main verweist lediglich auf den Standard-Branch des Remotes und ist kein eigener Branch.

Ist ein frisch gepushter Branch trotz git fetch nicht dabei, hilft oft:

git fetch --all --prune

--prune entfernt zusätzlich veraltete Remote-Tracking-Branches, die auf dem Server bereits gelöscht wurden. Eine ausführliche Einordnung, was der Befehl genau tut, finden Sie unter was macht git fetch.

Mehrere Remotes: wenn der Name mehrdeutig ist

Die DWIM-Automatik funktioniert nur, wenn genau ein Remote einen Branch dieses Namens hat. Arbeiten Sie mit einem Fork, existiert der Name feature-x vielleicht bei origin und bei upstream gleichzeitig. Dann verweigert Git die Vermutung:

fatal: 'feature-x' matched multiple (2) remote tracking branches

In diesem Fall benennen Sie den Remote explizit:

git switch -c feature-x upstream/feature-x

Damit ist eindeutig, aus welchem Remote der Branch stammt. --track erzwingt den Upstream-Bezug zusätzlich ausdrücklich:

git checkout --track upstream/feature-x

Detached HEAD vermeiden

Ein häufiger Stolperstein: git checkout origin/feature-x (mit origin/-Präfix) checkt nicht einen Branch aus, sondern den Commit, auf den der Remote-Tracking-Branch zeigt. Git landet im Zustand „detached HEAD”:

Note: switching to 'origin/feature-x'.
You are in 'detached HEAD' state. ...

Sie können hier zwar Dateien ansehen und sogar committen, aber neue Commits hängen an keinem Branch und gehen beim nächsten Wechsel leicht verloren. Zum reinen Ansehen ist das in Ordnung; zum Weiterarbeiten wollen Sie einen echten lokalen Branch. Lassen Sie deshalb das origin/-Präfix weg (git switch feature-x) oder erzeugen Sie sofort einen Branch mit git switch -c. Wenn Sie versehentlich in einem detached HEAD Commits gemacht haben, retten Sie diese mit git switch -c rettung, solange HEAD noch dort steht. Mehr zum gezielten Auschecken einzelner Stände lesen Sie unter wie checke ich einen Commit in Git aus.

Häufige Fehler und ihre Lösung

error: pathspec 'branch' did not match any file(s) known to git – Ihr lokales Repository kennt den Branch nicht. Führen Sie zuerst git fetch origin (oder git fetch --all) aus und prüfen Sie den Namen mit git branch -r. Achten Sie auf exakte Schreibweise, Git ist case-sensitive.

Der Branch fehlt nach git fetch – Möglicherweise ist die Refspec des Remotes eingeschränkt (z. B. bei einem flachen oder gefilterten Clone). Holen Sie den Branch dann gezielt:

git fetch origin feature-x:feature-x

Uncommitted changes blockieren den Wechsel – Meldet Git Your local changes would be overwritten, sichern Sie Ihren Stand vorher, etwa mit git stash, und wechseln dann. Prüfen Sie den Arbeitsbereich vorab mit git status.

FAQ

Was ist der Unterschied zwischen git switch und git checkout beim Auschecken? Für das Wechseln zu einem Branch tun beide dasselbe, inklusive der DWIM-Automatik, die aus einem Remote-Branch einen lokalen Tracking-Branch macht. git switch (ab Git 2.23) ist auf Branch-Wechsel spezialisiert und dadurch weniger fehleranfällig; git checkout kann daneben auch Dateien und einzelne Commits auschecken.

Muss ich vor dem Auschecken immer git fetch ausführen? Ja, sonst kennt Ihr lokales Repository neu erstellte Remote-Branches nicht. git fetch verändert Ihren Arbeitsstand und Ihre lokalen Branches nicht – es aktualisiert nur die Remote-Tracking-Referenzen. Erst danach kann Git den passenden Branch finden. Der Unterschied zu git pull wird unter holt git pull alle Branches ein erklärt.

Wie checke ich den Branch aus einem Fork (zweiten Remote) aus? Fügen Sie den Fork als Remote hinzu (git remote add upstream <url>), holen Sie ihn mit git fetch upstream und checken Sie explizit aus: git switch -c feature-x upstream/feature-x. Das explizite Nennen des Remotes verhindert die Mehrdeutigkeits-Fehlermeldung, wenn beide Remotes denselben Branch-Namen führen.