Wie ziehe ich einen Remote-Branch herunter?

Ein Kollege hat einen Branch auf GitHub gepusht, und Sie möchten diesen Stand lokal auschecken – finden ihn aber nicht. Das Problem: Git kennt nur die Branches, die es beim letzten Abgleich mit dem Server gesehen hat. Nach zwei Schritten – erst die Remote-Referenzen aktualisieren, dann den Branch auschecken – haben Sie den fremden Branch lokal vorliegen und können sofort damit arbeiten.

Der schnelle Weg in zwei Schritten

In den allermeisten Fällen genügen zwei Befehle:

git fetch origin
git switch branch-name

git fetch holt alle neuen Commits und Referenzen vom Remote (origin ist der Standardname des Servers), ohne Ihre lokalen Dateien oder Branches anzufassen. Es aktualisiert nur die sogenannten Remote-Tracking-Branches wie origin/branch-name.

git switch branch-name wechselt anschließend auf den Branch. Der Clou: Existiert lokal noch kein Branch dieses Namens, aber genau ein passender Remote-Tracking-Branch (origin/branch-name), legt Git den lokalen Branch automatisch an und richtet das Tracking ein. Git nennt dieses Verhalten „DWIM” (do what I mean). Ein späteres git pull weiß dann von selbst, woher es Änderungen holen soll.

Ob Sie wirklich auf dem richtigen Branch gelandet sind, bestätigt ein kurzes git status – die erste Zeile nennt den aktuellen Branch und den zugeordneten Upstream.

git switch gibt es seit Git 2.23 (August 2019). Auf älteren Versionen nutzen Sie stattdessen git checkout branch-name – das Ergebnis ist identisch.

Warum git fetch der erste Schritt ist

Direkt git switch fremder-branch scheitert oft mit:

fatal: invalid reference: fremder-branch

oder in älteren Versionen mit did not match any file(s) known to git. Der Grund ist fast immer: Ihr lokales Repository weiß noch nichts von diesem Branch, weil seit dem letzten fetch oder clone neue Branches hinzugekommen sind. Ein git fetch origin behebt das. Danach kennt Git die Referenz und der Wechsel klappt.

Sehen Sie sich nach dem Fetch an, welche Remote-Branches überhaupt existieren:

git branch -r        # nur Remote-Tracking-Branches
git branch -a        # lokale UND Remote-Branches

Was git fetch genau tut und wie es sich von git pull unterscheidet, erklärt der Beitrag Was macht git fetch? im Detail.

Tracking explizit einrichten

Manchmal wollen Sie den lokalen Branch anders benennen als den Remote-Branch oder das Tracking bewusst setzen. Dafür gibt es klare Varianten:

# Lokaler Name = Remote-Name, Tracking explizit
git switch --track origin/branch-name

# Eigener lokaler Name, Basis ist der Remote-Branch
git switch -c mein-lokaler-name origin/branch-name

Mit git checkout sehen die Entsprechungen so aus:

git checkout --track origin/branch-name
git checkout -b mein-lokaler-name origin/branch-name

Ob das Tracking korrekt sitzt, prüfen Sie mit git branch -vv – hinter dem Branch steht dann in eckigen Klammern der zugeordnete Upstream, etwa [origin/branch-name].

Mehrere Remotes: Wenn die Automatik streikt

Die DWIM-Automatik funktioniert nur, wenn genau ein Remote den Branch anbietet. Haben Sie mehrere Remotes (typisch bei Forks: origin und upstream) und beide führen einen feature-Branch, weiß Git nicht, welchen Sie meinen:

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

Dann müssen Sie den Remote ausdrücklich nennen:

git switch -c feature origin/feature

Wollen Sie im Zweifel immer denselben Remote bevorzugen, setzen Sie das dauerhaft:

git config --global checkout.defaultRemote origin

Einen bereits vorhandenen Branch aktualisieren

Haben Sie den Branch schon einmal ausgecheckt und wollen nur den neuesten Stand vom Server, erledigen Sie Herunterladen und Zusammenführen in einem Schritt:

git switch branch-name
git pull

git pull ist eine Kombination aus git fetch und git merge (oder git rebase, je nach Konfiguration). Ob Merge oder Rebase besser passt und worin der Unterschied liegt, behandelt Ist git fetch und merge dasselbe wie pull?.

Wichtig: git pull verändert Ihre Arbeitskopie. Haben Sie uncommittete Änderungen, stashen (git stash) oder committen Sie diese vorher, sonst bricht der Pull mit einer Warnung ab.

Typische Fehler und ihre Lösung

„detached HEAD” nach dem Auschecken. Wenn Sie versehentlich den Remote-Tracking-Branch direkt auschecken (git switch --detach origin/branch-name oder das ältere git checkout origin/branch-name), landen Sie im Zustand „detached HEAD”. Commits hängen dann an keinem Branch. Lösung: Legen Sie mit git switch -c branch-name einen richtigen lokalen Branch an.

Der Branch taucht nach fetch nicht auf. Möglicherweise lädt Ihr Remote gar nicht alle Branches. Prüfen Sie mit git config --get remote.origin.fetch – dort sollte +refs/heads/*:refs/remotes/origin/* stehen. Fehlt das Sternchen-Muster, wurde nur ein einzelner Branch geklont (--single-branch). Ein git remote set-branches origin "*" gefolgt von git fetch holt dann alle nach.

Gelöschte Branches geistern noch herum. Löscht jemand einen Branch auf dem Server, bleibt Ihre lokale Referenz origin/branch-name zunächst bestehen. Räumen Sie veraltete Referenzen auf:

git fetch --prune

Falscher Branch-Name. Groß- und Kleinschreibung sowie Slashes (feature/login) müssen exakt stimmen. Kopieren Sie den Namen im Zweifel direkt aus der Ausgabe von git branch -r.

FAQ

Was ist der Unterschied zwischen git fetch und git pull beim Herunterladen eines Branches? git fetch lädt die Commits nur herunter und aktualisiert die Remote-Tracking-Branches, ohne Ihre Arbeitskopie zu verändern. git pull macht dasselbe und führt die Änderungen zusätzlich sofort in Ihren aktuellen Branch zusammen. Zum erstmaligen Auschecken eines fremden Branches nutzen Sie fetch + switch; zum Aktualisieren eines Branches, auf dem Sie schon stehen, pull.

Muss ich für jeden Remote-Branch vorher git fetch ausführen? Nur wenn der Branch neu ist oder Sie ihn lokal noch nicht kennen. Nach einem frischen git clone sind alle zu diesem Zeitpunkt vorhandenen Branches bereits als Remote-Tracking-Referenzen da, und git switch name funktioniert direkt. Kommen später neue Branches auf dem Server hinzu, brauchen Sie erneut einen fetch.

Wie liste ich alle verfügbaren Remote-Branches auf? Mit git branch -r sehen Sie ausschließlich die Remote-Tracking-Branches, mit git branch -a zusätzlich Ihre lokalen. Ist die Liste veraltet, aktualisieren Sie sie vorher mit git fetch --prune. Verwandt dazu: Wie checke ich einen Remote-Branch aus?