Passer au contenu principal

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.

Un git worktree est un répertoire de travail séparé avec ses propres fichiers et branche, partageant le même historique de dépôt et la même télécommande que votre extraction principale. Exécuter chaque session Claude Code dans son propre worktree signifie que les modifications dans une session ne touchent jamais les fichiers d’une autre, vous pouvez donc avoir Claude construisant une fonctionnalité dans un terminal tout en corrigeant un bug dans un second. Cette page couvre l’isolation des worktrees dans la CLI. Tout ce qui suit suppose un dépôt git. Pour les autres systèmes de contrôle de version, voir Contrôle de version non-git. L’application de bureau crée automatiquement un worktree pour chaque nouvelle session. Les worktrees sont l’une des plusieurs façons d’exécuter Claude en parallèle. Ils isolent les modifications de fichiers, tandis que les subagents et les équipes d’agents coordonnent le travail lui-même. Voir Exécuter les agents en parallèle pour comparer les approches, ou passez directement à Isoler les subagents avec worktrees pour utiliser les worktrees et les subagents ensemble.

​
Démarrer Claude dans un worktree

Passez --worktree ou -w pour créer un worktree isolé et démarrer Claude dedans. Par défaut, le worktree est créé sous .claude/worktrees/<value>/ à la racine de votre dépôt, sur une nouvelle branche nommée worktree-<value> : 
claude --worktree feature-auth
Pour placer les worktrees ailleurs, configurez un hook WorktreeCreate. Exécutez la commande à nouveau avec un nom différent dans un autre terminal pour démarrer une deuxième session isolée : 
claude --worktree bugfix-123
Si vous omettez le nom, Claude en génère un tel que bright-running-fox : 
claude --worktree
Vous pouvez également demander à Claude de « travailler dans un worktree » pendant une session, et il en créera un avec l’outil EnterWorktree. Avant d’utiliser --worktree dans un répertoire pour la première fois, acceptez la boîte de dialogue de confiance de l’espace de travail en exécutant claude une fois dans ce répertoire. Si la confiance n’a pas encore été acceptée, --worktree se termine avec une erreur et vous invite à exécuter claude dans le répertoire en premier, y compris lorsqu’il est combiné avec -p.
Ajoutez .claude/worktrees/ à votre .gitignore pour que le contenu des worktrees n’apparaisse pas comme des fichiers non suivis dans votre extraction principale.

​
Choisir la branche de base

Les worktrees se ramifient à partir de la branche par défaut de votre dépôt, origin/HEAD, ils commencent donc à partir d’un arbre propre correspondant à la télécommande. Si aucune télécommande n’est configurée ou si la récupération échoue, le worktree revient à votre HEAD local actuel. Pour toujours vous ramifier à partir du HEAD local à la place, définissez worktree.baseRef sur "head" dans paramètres. Définir baseRef sur "head" fait que les nouveaux worktrees portent vos commits non poussés et l’état de la branche de fonctionnalité, ce qui est utile lors de l’isolation des subagents qui doivent opérer sur un travail en cours. Le paramètre n’accepte que "fresh" ou "head", pas des refs git arbitraires : 
{
  "worktree": {
    "baseRef": "head"
  }
}
Pour vous ramifier à partir d’une demande de tirage spécifique, passez le numéro de PR préfixé par #, ou une URL complète de demande de tirage GitHub. Claude Code récupère pull/<number>/head à partir de origin et crée le worktree à .claude/worktrees/pr-<number> : 
claude --worktree "#1234"
Pour un contrôle total sur la façon dont les worktrees sont créés, configurez un hook WorktreeCreate, qui remplace entièrement la logique git worktree par défaut.

​
Copier les fichiers gitignorés dans les worktrees

Un worktree est une extraction fraîche, donc les fichiers non suivis comme .env ou .env.local de votre dépôt principal ne sont pas présents. Pour les copier automatiquement quand Claude crée un worktree, ajoutez un fichier .worktreeinclude à la racine de votre projet. Le fichier utilise la syntaxe .gitignore. Seuls les fichiers qui correspondent à un motif et sont également gitignorés sont copiés, donc les fichiers suivis ne sont jamais dupliqués. Ce .worktreeinclude copie deux fichiers env et une configuration de secrets dans chaque nouveau worktree :
.worktreeinclude
.env
.env.local
config/secrets.json
Cela s’applique aux worktrees créés avec --worktree, worktrees de subagents, et aux sessions parallèles dans l’application de bureau.

​
Isoler les subagents avec worktrees

Les subagents peuvent s’exécuter dans leurs propres worktrees pour que les modifications parallèles ne se heurtent pas. Demandez à Claude d’« utiliser les worktrees pour vos agents », ou définissez-le de manière permanente sur un subagent personnalisé en ajoutant isolation: worktree au frontmatter. Chaque subagent obtient un worktree temporaire qui est supprimé automatiquement quand le subagent se termine sans modifications.

​
Nettoyer les worktrees

Quand vous quittez une session worktree, le nettoyage dépend de si vous avez apporté des modifications :
  • Pas de modifications : le worktree et sa branche sont supprimés automatiquement
  • Des modifications ou des commits existent : Claude vous demande de conserver ou de supprimer le worktree. Conserver préserve le répertoire et la branche pour que vous puissiez revenir plus tard. Supprimer supprime le répertoire worktree et sa branche, en supprimant toutes les modifications non validées et les commits
  • Exécutions non interactives : les worktrees créés avec --worktree aux côtés de -p ne sont pas nettoyés automatiquement puisqu’il n’y a pas d’invite de sortie. Supprimez-les avec git worktree remove
Les worktrees de subagents orphelins par un crash ou une exécution interrompue sont supprimés au démarrage une fois qu’ils sont plus anciens que votre paramètre cleanupPeriodDays, à condition qu’ils n’aient pas de modifications non validées, pas de fichiers non suivis et pas de commits non poussés. Les worktrees que vous créez avec --worktree ne sont jamais supprimés par ce balayage.

​
Gérer les worktrees manuellement

Pour un contrôle total sur l’emplacement du worktree et la configuration de la branche, créez des worktrees directement avec Git. Ceci est utile quand vous devez extraire une branche existante spécifique ou placer le worktree en dehors du dépôt. Créer un worktree sur une nouvelle branche : 
git worktree add ../project-feature-a -b feature-a
Créer un worktree à partir d’une branche existante : 
git worktree add ../project-bugfix bugfix-123
Démarrer Claude dans le worktree : 
cd ../project-feature-a && claude
Lister vos worktrees : 
git worktree list
Supprimer un quand vous en avez terminé : 
git worktree remove ../project-feature-a
Voir la documentation Git worktree pour la référence complète des commandes. N’oubliez pas d’initialiser votre environnement de développement dans chaque nouveau worktree : installez les dépendances, configurez les environnements virtuels, ou exécutez tout ce que votre configuration de projet nécessite.

​
Contrôle de version non-git

L’isolation des worktrees utilise git par défaut. Pour SVN, Perforce, Mercurial ou d’autres systèmes, configurez les hooks WorktreeCreate et WorktreeRemove pour fournir une logique de création et de nettoyage personnalisée. Parce que le hook remplace le comportement git par défaut, .worktreeinclude n’est pas traité quand vous utilisez --worktree. Copiez plutôt tous les fichiers de configuration locale à l’intérieur de votre script de hook. Ce hook WorktreeCreate lit le nom du worktree à partir de stdin, extrait une copie de travail SVN fraîche, et imprime le chemin du répertoire pour que Claude Code puisse l’utiliser comme répertoire de travail de la session : 
{
  "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\"'"
          }
        ]
      }
    ]
  }
}
Associez-le à un hook WorktreeRemove pour nettoyer quand la session se termine. Voir la référence des hooks pour le schéma d’entrée et un exemple de suppression.

​
Voir aussi

Les worktrees gèrent l’isolation des fichiers. Les pages connexes ci-dessous couvrent la délégation du travail dans ces extractions isolées et le basculement entre les sessions que vous créez :