Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Ein Git-Worktree ist ein separates Arbeitsverzeichnis mit eigenen Dateien und Branch, das die gleiche Repository-Historie und Remote wie Ihr Haupt-Checkout teilt. Das Ausführen jeder Claude Code-Sitzung in ihrem eigenen Worktree bedeutet, dass Änderungen in einer Sitzung niemals Dateien in einer anderen berühren, sodass Claude in einem Terminal ein Feature entwickeln kann, während Sie in einem zweiten einen Bug beheben. Diese Seite behandelt die Worktree-Isolation in der CLI. Alles unten setzt ein Git-Repository voraus. Für andere Versionskontrollsysteme siehe Non-Git-Versionskontrolle. Die Desktop-App erstellt für jede neue Sitzung automatisch einen Worktree. Worktrees sind eine von mehreren Möglichkeiten, Claude parallel auszuführen. Sie isolieren Datei-Änderungen, während Subagents und Agent-Teams die Arbeit selbst koordinieren. Siehe Agenten parallel ausführen, um die Ansätze zu vergleichen, oder springen Sie direkt zu Subagents mit Worktrees isolieren, um Worktrees und Subagents zusammen zu verwenden.

​
Starten Sie Claude in einem Worktree

Übergeben Sie --worktree oder -w, um einen isolierten Worktree zu erstellen und Claude darin zu starten. Standardmäßig wird der Worktree unter .claude/worktrees/<value>/ in Ihrem Repository-Root erstellt, auf einem neuen Branch namens worktree-<value>: 
claude --worktree feature-auth
Um Worktrees an anderer Stelle zu platzieren, konfigurieren Sie einen WorktreeCreate-Hook. Führen Sie den Befehl erneut mit einem anderen Namen in einem anderen Terminal aus, um eine zweite isolierte Sitzung zu starten: 
claude --worktree bugfix-123
Wenn Sie den Namen weglassen, generiert Claude einen Namen wie bright-running-fox: 
claude --worktree
Sie können Claude auch während einer Sitzung bitten, „in einem Worktree zu arbeiten”, und es wird einen mit dem EnterWorktree-Tool erstellen. Bevor Sie --worktree in einem Verzeichnis zum ersten Mal verwenden, akzeptieren Sie den Dialog zum Vertrauen des Arbeitsbereichs, indem Sie claude einmal in diesem Verzeichnis ausführen. Wenn das Vertrauen noch nicht akzeptiert wurde, beendet sich --worktree mit einem Fehler und fordert Sie auf, zuerst claude im Verzeichnis auszuführen, auch wenn es mit -p kombiniert wird.
Fügen Sie .claude/worktrees/ zu Ihrer .gitignore hinzu, damit Worktree-Inhalte nicht als nicht verfolgte Dateien in Ihrem Haupt-Checkout angezeigt werden.

​
Wählen Sie den Basis-Branch

Worktrees verzweigen sich vom Standard-Branch Ihres Repositories, origin/HEAD, sodass sie von einem sauberen Tree starten, der dem Remote entspricht. Wenn kein Remote konfiguriert ist oder der Abruf fehlschlägt, fällt der Worktree auf Ihren aktuellen lokalen HEAD zurück. Um immer vom lokalen HEAD zu verzweigen, setzen Sie worktree.baseRef auf "head" in Einstellungen. Das Setzen von baseRef auf "head" führt dazu, dass neue Worktrees Ihre nicht gepushten Commits und den Feature-Branch-Status tragen, was nützlich ist, wenn Sie Subagents isolieren, die an laufenden Arbeiten arbeiten müssen. Die Einstellung akzeptiert nur "fresh" oder "head", nicht beliebige Git-Refs: 
{
  "worktree": {
    "baseRef": "head"
  }
}
Um von einem bestimmten Pull Request zu verzweigen, übergeben Sie die PR-Nummer mit # vorangestellt oder eine vollständige GitHub-Pull-Request-URL. Claude Code ruft pull/<number>/head von origin ab und erstellt den Worktree unter .claude/worktrees/pr-<number>: 
claude --worktree "#1234"
Für vollständige Kontrolle über die Erstellung von Worktrees konfigurieren Sie einen WorktreeCreate-Hook, der die Standard-git worktree-Logik vollständig ersetzt.

​
Kopieren Sie gitignorierte Dateien in Worktrees

Ein Worktree ist ein frischer Checkout, daher sind nicht verfolgte Dateien wie .env oder .env.local aus Ihrem Haupt-Repository nicht vorhanden. Um sie automatisch zu kopieren, wenn Claude einen Worktree erstellt, fügen Sie eine .worktreeinclude-Datei zu Ihrem Projekt-Root hinzu. Die Datei verwendet .gitignore-Syntax. Nur Dateien, die einem Muster entsprechen und auch gitignoriert sind, werden kopiert, sodass verfolgte Dateien niemals dupliziert werden. Diese .worktreeinclude kopiert zwei Env-Dateien und eine Secrets-Konfiguration in jeden neuen Worktree:
.worktreeinclude
.env
.env.local
config/secrets.json
Dies gilt für Worktrees, die mit --worktree erstellt werden, Subagent-Worktrees und parallele Sitzungen in der Desktop-App.

​
Isolieren Sie Subagents mit Worktrees

Subagents können in ihren eigenen Worktrees ausgeführt werden, sodass parallele Änderungen nicht kollidieren. Bitten Sie Claude, „Worktrees für Ihre Agenten zu verwenden”, oder setzen Sie es dauerhaft auf einem benutzerdefinierten Subagent, indem Sie isolation: worktree zum Frontmatter hinzufügen. Jeder Subagent erhält einen temporären Worktree, der automatisch entfernt wird, wenn der Subagent ohne Änderungen beendet wird.

​
Bereinigen Sie Worktrees

Wenn Sie eine Worktree-Sitzung beenden, hängt die Bereinigung davon ab, ob Sie Änderungen vorgenommen haben:
  • Keine Änderungen: Der Worktree und sein Branch werden automatisch entfernt
  • Änderungen oder Commits vorhanden: Claude fordert Sie auf, den Worktree zu behalten oder zu entfernen. Das Behalten bewahrt das Verzeichnis und den Branch, sodass Sie später zurückkehren können. Das Entfernen löscht das Worktree-Verzeichnis und seinen Branch und verwirft alle nicht committeten Änderungen und Commits
  • Nicht-interaktive Ausführungen: Worktrees, die mit --worktree zusammen mit -p erstellt werden, werden nicht automatisch bereinigt, da es keine Exit-Eingabeaufforderung gibt. Entfernen Sie sie mit git worktree remove
Subagent-Worktrees, die durch einen Absturz oder unterbrochene Ausführung verwaist sind, werden beim Start entfernt, sobald sie älter als Ihre cleanupPeriodDays-Einstellung sind, sofern sie keine nicht committeten Änderungen, keine nicht verfolgten Dateien und keine nicht gepushten Commits haben. Worktrees, die Sie mit --worktree erstellen, werden niemals durch diese Bereinigung entfernt.

​
Verwalten Sie Worktrees manuell

Für vollständige Kontrolle über den Worktree-Speicherort und die Branch-Konfiguration erstellen Sie Worktrees direkt mit Git. Dies ist nützlich, wenn Sie einen bestimmten vorhandenen Branch auschecken oder den Worktree außerhalb des Repositories platzieren müssen. Erstellen Sie einen Worktree auf einem neuen Branch: 
git worktree add ../project-feature-a -b feature-a
Erstellen Sie einen Worktree aus einem vorhandenen Branch: 
git worktree add ../project-bugfix bugfix-123
Starten Sie Claude im Worktree: 
cd ../project-feature-a && claude
Listen Sie Ihre Worktrees auf: 
git worktree list
Entfernen Sie einen, wenn Sie damit fertig sind: 
git worktree remove ../project-feature-a
Siehe die Git-Worktree-Dokumentation für die vollständige Befehlsreferenz. Denken Sie daran, Ihre Entwicklungsumgebung in jedem neuen Worktree zu initialisieren: Installieren Sie Abhängigkeiten, richten Sie virtuelle Umgebungen ein oder führen Sie aus, was die Einrichtung Ihres Projekts erfordert.

​
Non-Git-Versionskontrolle

Die Worktree-Isolation verwendet standardmäßig Git. Für SVN, Perforce, Mercurial oder andere Systeme konfigurieren Sie WorktreeCreate- und WorktreeRemove-Hooks, um benutzerdefinierte Erstellungs- und Bereinigungslogik bereitzustellen. Da der Hook das Standard-Git-Verhalten ersetzt, wird .worktreeinclude nicht verarbeitet, wenn Sie --worktree verwenden. Kopieren Sie stattdessen alle lokalen Konfigurationsdateien in Ihr Hook-Skript. Dieser WorktreeCreate-Hook liest den Worktree-Namen aus stdin, checkt eine frische SVN-Arbeitskopie aus und gibt den Verzeichnispfad aus, damit Claude Code ihn als Arbeitsverzeichnis der Sitzung verwenden kann: 
{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}
Kombinieren Sie es mit einem WorktreeRemove-Hook, um die Bereinigung durchzuführen, wenn die Sitzung endet. Siehe die Hooks-Referenz für das Eingabeschema und ein Entfernungsbeispiel.

​
Siehe auch

Worktrees handhaben die Datei-Isolation. Die verwandten Seiten unten behandeln die Delegierung von Arbeit in diese isolierten Checkouts und das Wechseln zwischen den Sitzungen, die Sie erstellen: