git worktree

Was git worktree macht

Der Befehl git worktree ermöglicht es, mehr als einen Branch gleichzeitig aus einem einzigen Repository auszuchecken. Jeder Worktree ist ein separates Arbeitsverzeichnis mit einem eigenen ausgecheckten Branch und einem eigenen Index, aber alle teilen sich denselben .git-Objektspeicher, die History, Refs und die Konfiguration. Es ist der saubere Weg, um parallel an zwei Branches zu arbeiten, ohne das Repository zweimal zu klonen.

Das Verzeichnis, in das du geklont hast, ist dein Main Worktree; jedes Verzeichnis, das du mit git worktree add erstellst, ist ein Linked Worktree. Linked Worktrees sind ressourcenschonend: Sie speichern nur eine kleine .git-Datei (keinen Ordner), die auf das gemeinsame Repository zurückverweist, und kosten daher auf der Festplatte kaum etwas im Vergleich zu einem zweiten Klon.

Diese Seite behandelt, wann ein Worktree sinnvoll ist, wie man Worktrees hinzufügt, auflistet, verschiebt und entfernt, welche Regeln Git durchsetzt und welche häufigen Fallstricke es gibt.

Das Problem, das er löst

Stell dir vor, du arbeitest tief in einem Feature-Branch, als ein dringender Fehlerbericht eintrifft. Normalerweise müsstest du deine Arbeit stashen, den Branch wechseln, den Fehler beheben, zurückwechseln und den Stash wieder anwenden – das ist störend und fehleranfällig. Mit Worktrees erstellst du einfach ein zweites Arbeitsverzeichnis, das auf den Hotfix-Branch ausgecheckt ist, behebst den Fehler dort und lässt deine Feature-Arbeit völlig unberührt. Wenn der Build die beiden Zustände nebeneinander benötigt – etwa um das Verhalten zu vergleichen oder zwei lange Test-Suites gleichzeitig auszuführen – glänzen Worktrees dort, wo Stashing nicht hilft.

Einen Worktree hinzufügen

Gib git worktree add einen Pfad und einen Branch an. Um einen vorhandenen Branch in ein Nachbarverzeichnis auszuchecken:

git worktree add ../hotfix hotfix

Dadurch wird ../hotfix mit dem ausgecheckten Branch hotfix erstellt:

Preparing worktree (checking out 'hotfix')
HEAD is now at 1a2b3c4 Add login form

Um gleichzeitig einen neuen Branch zu erstellen, verwende -b. Das letzte Argument ist der Startpunkt, auf dem der neue Branch basiert:

git worktree add -b experiment ../experiment main

Du hast jetzt zwei unabhängige Arbeitsverzeichnisse, die von einem einzigen Repository gesichert werden. Wenn du den Branch ganz weglässt, erstellt Git einen Branch, der nach dem letzten Pfadbestandteil benannt ist:

git worktree add ../docs    # creates and checks out a branch named "docs"

Um einen Commit zu inspizieren, ohne einen Branch dorthin zu legen – praktisch zum Testen eines alten Releases – füge ihn im Detached-HEAD-Zustand hinzu:

git worktree add --detach ../v1-check v1.0.0

Siehe Detached HEAD für eine Erklärung dieses Zustands.

Worktrees auflisten

Alle Arbeitsverzeichnisse des Repositories anzeigen:

git worktree list

Die Ausgabe zeigt jeden Pfad, den Commit, auf dem er steht, und den Branch (oder (detached HEAD)):

/home/dev/project          1a2b3c4 [main]
/home/dev/hotfix           9f8e7d6 [hotfix]
/home/dev/v1-check         0011223 (detached HEAD)

Füge --porcelain für ein stabiles, skriptfreundliches Format hinzu.

Worktrees verschieben und entfernen

Um einen Linked Worktree zu verschieben, lass Git seine Buchhaltung aktualisieren, anstatt die Shell-Methode mv zu verwenden:

git worktree move ../hotfix ../urgent-fix

Wenn du mit einem Worktree fertig bist, entferne ihn (das löscht sein Verzeichnis):

git worktree remove ../urgent-fix

Git weigert sich, einen Worktree mit nicht committeten Änderungen oder nicht versionierten Dateien zu entfernen, sodass du nicht versehentlich Arbeit verlierst. Wenn du sicher bist, übersteuere diese Prüfung mit --force:

git worktree remove --force ../urgent-fix

Wenn du den Ordner eines Worktrees manuell mit rm -rf gelöscht hast, enthält das Repository noch einen veralteten Verwaltungseintrag. Bereinige ihn mit:

git worktree prune

Einen Worktree sperren

Wenn ein Worktree auf einem Wechseldatenträger oder einer Netzwerkfreigabe liegt, sperre ihn, damit prune seine Buchhaltung nie entfernt, während das Laufwerk nicht eingebunden ist:

git worktree lock ../usb-backup --reason "external disk"
git worktree unlock ../usb-backup

Befehlsübersicht

Regeln und Fallstricke

• Ein Branch, ein Worktree. Ein Branch kann immer nur in einem Worktree gleichzeitig ausgecheckt sein. Wenn du versuchst, einen Worktree für einen bereits andernorts ausgecheckten Branch hinzuzufügen, verweigert Git dies mit fatal: '<branch>' is already used by worktree at .... Das garantiert, dass zwei Verzeichnisse nie um denselben Branch-Zeiger konkurrieren können. Verwende --detach oder einen neuen Branch mit -b, wenn du denselben Commit an zwei Stellen benötigst.
• Lokale Änderungen werden nicht geteilt. Jeder Worktree hat seine eigenen Arbeitsdateien, seinen eigenen Index und seinen eigenen Stash. Commits, Branches, Tags und Remotes werden geteilt, da sie im gemeinsamen .git-Speicher liegen.
• Den Main Worktree entfernen. Du kannst den ursprünglichen (Main) Worktree nicht mit git worktree remove entfernen – nur Linked Worktrees können entfernt werden.
• Bare Repositories eignen sich hervorragend als Host für Worktrees: Klone mit git clone --bare, und füge dann jeden Working-Branch als eigenen Worktree hinzu, sodass die Repository-Daten von jedem Checkout getrennt bleiben.

Verwandte Befehle

• git branch — Branches erstellen und verwalten, die du in Worktrees auscheckst.
• git switch — Zwischen Branches innerhalb eines einzigen Arbeitsverzeichnisses wechseln.
• git stash — Die ältere Einzelverzeichnis-Alternative zu einem schnellen Worktree.

Übung