Forking-Workflow

Übersicht

Der Forking-Workflow ist das Standardmodell für Open-Source-Projekte und alle Umgebungen, in denen Mitwirkende keinen direkten Push-Zugriff auf das Haupt-Repository haben. Anstatt in ein gemeinsames Repository zu pushen, arbeitet jeder Mitwirkende in seiner eigenen serverseitigen Kopie — einem Fork — und schlägt Änderungen über einen Pull Request vor. So gelangen täglich Millionen von Beiträgen zu Projekten auf GitHub und GitLab.

Diese Seite erklärt, was ein Fork ist, wie er sich von einem Shared-Repository-Workflow unterscheidet, welche genauen Befehle zum Klonen, Konfigurieren von Remotes, Pushen und Öffnen eines Pull Requests nötig sind — und vor allem, wie du deinen Fork synchron hältst, damit deine Beiträge leicht zusammengeführt werden können.

Der entscheidende Unterschied

Im Feature-Branch-Workflow pushen alle Branches in ein gemeinsames Repository. Der Forking-Workflow fügt eine Ebene hinzu: Es gibt nun zwei serverseitige Repositories — das offizielle Upstream-Repo, in das du nicht schreiben kannst, und deinen Fork, den du vollständig kontrollierst. Du pushst in deinen Fork und bittest Upstream, von dort zu pullen.

Dies wird manchmal als triangularer Workflow bezeichnet, wegen der Beziehung zwischen den drei Kopien:

        upstream (official repo, read-only to you)
          ▲   │
   pull   │   │ fork (one click, server-side)
  request │   ▼
        your fork (origin) ──clone──▶ your laptop
                            ◀──push──

Du fetchst von upstream, pushst zu origin (deinem Fork), und der Pull Request ist die Brücke, die einen Maintainer bittet, deinen Branch aus deinem Fork in Upstream zu mergen.

Schritt für Schritt

1. Fork das Upstream-Repository auf der Hosting-Plattform. Dadurch wird your-fork unter deinem Konto erstellt — eine vollständige serverseitige Kopie.

2. Klone deinen Fork auf deinen Rechner:

git clone https://github.com/you/project.git
cd project

3. Füge Upstream als Remote hinzu, damit du die neuesten Änderungen des Projekts pullen kannst:

git remote add upstream https://github.com/original/project.git

Dein Klon hat nun zwei Remotes. Überprüfe sie mit git remote -v:

origin    https://github.com/you/project.git (fetch)
origin    https://github.com/you/project.git (push)
upstream  https://github.com/original/project.git (fetch)
upstream  https://github.com/original/project.git (push)

origin zeigt auf deinen Fork (wohin du pushst); upstream zeigt auf das offizielle Repo (von dem du fetchst). Siehe git remote zur Verwaltung dieser Remotes.

4. Erstelle einen Branch und arbeite. Branchen immer von einem aktuellen main ab — committe niemals direkt in das main deines Forks, damit es ein sauberer Spiegel von Upstream bleibt:

git switch -c fix/typo-in-docs
# ...make changes and commit...
git push -u origin fix/typo-in-docs

Das Flag -u (--set-upstream) verknüpft deinen lokalen Branch mit dem auf deinem Fork, sodass du später einfach git push ausführen kannst.

5. Öffne einen Pull Request von dem Branch deines Forks zum Main-Branch von Upstream. In der Web-Oberfläche ist das ein Knopf; mit GitHub's CLI geht es auch vom Terminal:

gh pr create --base main --head you:fix/typo-in-docs

Maintainer prüfen ihn, fordern bei Bedarf Änderungen an und mergen ihn, wenn sie zufrieden sind. Wenn Änderungen gewünscht werden, committe und führe erneut git push aus — der offene Pull Request wird automatisch aktualisiert.

Mit Upstream synchron bleiben

Das Projekt entwickelt sich weiter, während du arbeitest. Aktualisiere deinen Fork aus Upstream, bevor du neue Branches erstellst. Nutze git fetch, um die Commits von Upstream herunterzuladen, und füge sie dann mit git merge (oder Rebase) ein:

git switch main
git fetch upstream
git merge upstream/main      # fast-forward main onto upstream
git push origin main         # update your fork's main on the server

Da du selbst nie in main commitest, ist dieser Merge immer ein sauberer Fast-Forward — keine Konflikte. Du kannst das mit git merge --ff-only upstream/main erzwingen, was laut fehlschlägt, wenn main divergiert ist.

Einen laufenden Feature-Branch aktualisieren

Wenn dein Branch zurückfällt, während ein Review sich hinzieht, bringe die neuen Commits von Upstream hinein. Rebasing sorgt für eine lineare History, die Maintainer üblicherweise bevorzugen:

git fetch upstream
git switch fix/typo-in-docs
git rebase upstream/main
git push --force-with-lease    # rewrite your fork's branch safely

--force-with-lease verweigert das Überschreiben des Remote-Branches, falls zwischenzeitlich jemand anderes gepusht hat — das macht es weit sicherer als ein einfaches --force. Wenn du das Umschreiben der History vermeiden möchtest, führe stattdessen git merge upstream/main aus. Siehe git rebase und Merge-Konflikte für die Details.

Warum es funktioniert

Das Forking-Modell ermöglicht es einem Projekt, Beiträge von jedermann anzunehmen, während das offizielle Repository gesperrt bleibt — nur Maintainer können mergen. Mitwirkende benötigen keine besonderen Berechtigungen, die Überprüfung findet öffentlich bei jedem Pull Request statt, und die Upstream-History bleibt sauber. Für unvertraute, groß angelegte Zusammenarbeit ist es der sicherste der verbreiteten Git-Workflows.

Verwende ihn, wenn Mitwirkende keinen Push-Zugriff haben (die meisten Open-Source-Projekte). Wenn alle im selben Team und vertrauenswürdig sind, vermeidet der einfachere Feature-Branch-Workflow oder Gitflow den zusätzlichen Fork. Vergleiche sie nebeneinander in Git-Workflows.

Übungen