Worktree intégré Cursor : utilisation avancée

06-cursor-cli-with-worktree couvre worktree + CLI manuel en parallèle ; ce billet se concentre sur l'utilisation avancée des worktrees créés automatiquement par Cursor (Agent parallèle / Apply) : comment enchaîner plusieurs tâches, choisir Merge ou Full Overwrite à l'Apply, gérer les conflits et utiliser git worktree list au quotidien. On laisse l’intro de côté et on passe à la pratique.

Scénario avancé 1 : Plusieurs tâches en parallèle, revue puis Apply

Une fonctionnalité peut être découpée en plusieurs « sous-tâches », chacune exécutée par un Agent dans son worktree ; vous n’appliquez que celles que vous voulez, pas tout d’un coup.

Exemple : Vous voulez faire « refactor utils », « ajouter des tests unitaires » et « générer la doc API » en même temps :

• Démarrez trois Agents en parallèle (ou un par un, chacun dans un worktree) avec des prompts différents
• À la fin vous avez trois résultats : peut-être que le « refactor » est bon, les « tests » à retoucher, les « docs » vous les jetez
• Appliquez uniquement la carte « refactor » ; laissez les autres sans Apply pour que seul le refactor soit fusionné dans main — les deux autres ne touchent pas au répertoire principal

Point avancé : Vous n’êtes pas obligé de tout commiter d’un coup ; vous pouvez « Apply par tâche, Apply par carte », et main ne reçoit que ce que vous avez accepté.

Scénario avancé 2 : Merge ou Full Overwrite à l’Apply ?

À l’Apply, Cursor tente de fusionner proprement. Si le même Best-of-N ou plusieurs Apply créent des conflits, il demandera :

En pratique : une tâche, un Agent, peu de fichiers → le merge suffit souvent. Même requête lancée avec plusieurs modèles (Best-of-N) et vous appliquez une partie de la carte A et une partie de la B → les conflits sont probables ; alors soit vous n’appliquez qu’une carte, soit vous utilisez le merge et résolvez fichier par fichier. Évitez Full Overwrite sur le même ensemble de fichiers venant de plusieurs cartes — ils s’écraseront entre eux.

Scénario avancé 3 : Comportement quand main a des changements non commités

Lors de la création d’un worktree, Cursor copie les changements suivis et les nouveaux fichiers du répertoire principal dans le worktree (les fichiers ignorés par Git ne le sont pas). Donc :

• Vous modifiez quelque chose sur main sans commit, puis vous démarrez un Agent en worktree → l’Agent travaille par-dessus votre « état actuel » ; à l’Apply, vous fusionnez « vos changements non commités + changements de l’Agent »
• Si vous voulez que les tâches parallèles partent d’un main propre, faites git stash ou un commit avant, puis créez le worktree, pour ne pas mélanger « WIP + changements Agent » et avoir plus de conflits à l’Apply

Vous pouvez aussi faire l’inverse : volontairement laisser du WIP sur main, créer un worktree pour des changements expérimentaux, puis utiliser le merge à l’Apply pour ne ramener que ce qui vous plaît ; laissez le reste dans le worktree sans Apply.

Scénario avancé 4 : Inspecter et nettoyer avec git worktree list

Les worktrees créés par Cursor apparaissent dans git worktree list ; les chemins sont en général sous .cursor/worktrees/<repo>/<id> :

git worktree list

Bonnes habitudes :

• Après Apply et une fois main correct, Cursor gère le nombre automatiquement ; si la liste contient beaucoup de worktrees et que le disque est juste, regardez les réglages Cursor (ex. cursor.worktreeMaxCount, intervalle de nettoyage) ou fermez les fenêtres de projet inutilisées pour que les anciens worktrees soient nettoyés
• En debug : la liste montre combien de « sandboxes » existent et sur quelle branche, pour ne pas confondre main et worktrees Agent

Évitez d’exécuter git worktree remove à la main sur les chemins créés par Cursor sauf si vous êtes sûr que l’Agent est terminé ; sinon l’état interne de Cursor peut se désynchroniser.

Scénario avancé 5 : Quand des Agents parallèles touchent aux mêmes fichiers

Si vous lancez deux Agents, l’un modifiant src/auth/ et l’autre src/api/, en général ils ne conflictuent pas — appliquez l’un puis l’autre (l’ordre importe peu ; le merge se résout souvent tout seul).

Si les deux Agents modifient le même fichier (ex. tous les deux touchent package.json ou le même config.ts) :

• Appliquez le premier → main a ces changements
• Appliquez le second → vous entrez dans le flux de merge et pouvez avoir des conflits
• Utilisez l’UI de conflits de Cursor pour choisir « garder cette partie de main, cette partie du worktree », ou si vous voulez entièrement la version du second worktree, utilisez Full Overwrite

Stratégie : En planifiant des tâches parallèles, essayez de garder des ensembles de fichiers non chevauchants par Agent (ex. un répertoire frontend, un backend) ; vous aurez rarement à résoudre les conflits à la main.

Résumé

• Plusieurs tâches en parallèle : Découpez en sous-tâches par worktree, revoyez puis n’appliquez que les cartes voulues ; main ne reçoit que ce que vous acceptez
• Choix à l’Apply : Utilisez Merge pour garder une partie de main ; utilisez Full Overwrite quand le fichier du worktree doit gagner ; évitez plusieurs Full Overwrite sur les mêmes fichiers venant de plusieurs cartes
• État du répertoire principal : Les changements non commités sont copiés dans le worktree ; pour une base propre, stash/commit avant ; ou laissez du WIP exprès pour « worktree expérimental + merge sélectif »
• Gestion : Utilisez git worktree list pour inspecter et vous aligner sur le nettoyage de Cursor ; gardez des ensembles de fichiers par tâche non chevauchants pour limiter les conflits

Suivant : 09-worktree-advanced — Best-of-N multi-modèles, worktrees.json et nettoyage.