Worktrees & hooks Git

Préparer un worktree pour un agent IA consiste à installer les dépendances dans son checkout, fournir sa configuration ignorée, puis réserver des ports et une base de test propres au ticket. Un dossier Git séparé ne sépare pas les services de la machine.

1. Activez les worktrees et lancez deux tickets indépendants A et B. Utilisez le chemin retourné par Singularity pour chaque ticket ; laissez l’application gérer les branches et dossiers.
2. Depuis la racine de chaque checkout, exécutez la commande du dépôt, par exemple pnpm install --frozen-lockfile pour un projet pnpm. Ne partagez pas node_modules, les sorties de build ou les caches modifiables entre checkouts.
3. Recréez les fichiers ignorés depuis un modèle sans secrets. Vérifiez git check-ignore .env.local et git status --short. Fournissez les secrets via votre gestionnaire habituel, sans les copier dans un ticket, un log ou un commit ; n’utilisez pas la base de production pour les tests.
4. Attribuez un port et une base distincts : A utilise 43101 et .local/ticket-a.sqlite, B utilise 43102 et .local/ticket-b.sqlite. Pour un service externe, utilisez deux bases ou schémas de test et adaptez les variables à votre application.
5. Lancez les tests dans les deux terminaux au même moment. Un port occupé doit faire échouer le test ; choisissez alors un autre port libre et consignez-le dans le ticket. Ne tuez pas un processus inconnu.

Un exemple reproductible pour deux tickets

Le mode d’emploi téléchargeable installe un petit projet Node 24+ avec npm ci, sans dépendance tierce. Téléchargez ses trois fichiers dans chaque checkout : package.json, package-lock.json et isolation.test.mjs. Créez uniquement la configuration A dans A, et B dans B.

# Checkout A : examples/worktree-setup/.env.local
TICKET_ID=ticket-a
PORT=43101
TEST_DB_PATH=.local/ticket-a.sqlite
# Checkout B : examples/worktree-setup/.env.local
TICKET_ID=ticket-b
PORT=43102
TEST_DB_PATH=.local/ticket-b.sqlite

npm test vérifie la réponse HTTP du ticket et le propriétaire de sa base SQLite, avec 1,5 seconde de chevauchement. Le test ferme serveur et base même en cas d’échec. Cette recette vérifie l’isolation des ressources de cet exemple, pas tous les environnements applicatifs.

Arrêter, nettoyer ou séquencer

Arrêtez vos serveurs de développement avant de supprimer le worktree, puis effacez uniquement les bases de test de ce ticket. Conservez les changements utiles avant le nettoyage Git. Si deux tickets doivent utiliser le même émulateur, la même base ou un port imposé, séquencez-les avec une dépendance : A s’arrête et libère la ressource avant B. La file d’intégration sérialise les commits, pas les serveurs.

Ces commandes appartiennent au dépôt exemple ; elles ne constituent pas une API de préparation Singularity. worktrees.json de Cursor et les scripts de Superset ou Conductor ne sont pas présentés comme des configurations prises en charge ici. Voir les premiers pas, l’orchestration et le protocole comparatif commun.

Un worktree Git est un second dossier de travail rattaché au même dépôt. Il possède sa propre branche et ses propres fichiers extraits, tout en partageant l’historique Git avec le dossier principal. Vous pouvez donc garder une modification inachevée ouverte dans votre arbre habituel pendant qu’un autre travail avance ailleurs.

Ce n’est ni une copie complète du dépôt, ni une branche abstraite sans fichiers : les outils, tests et éditeurs peuvent l’ouvrir normalement.

Avec le réglage actif, chaque exécution d’agent reçoit son propre worktree sous .singularity-worktrees/<uuid>/ et une branche dédiée. Le workflow demande à l’agent de lire, modifier, tester et commiter dans ce dossier, pour séparer ses changements de vos fichiers non commités.

Cette séparation réduit le recouvrement des fichiers entre agents. Elle ne constitue pas une restriction d’accès du processus au reste du système.

Non. Un worktree Git est un dossier de travail séparé, pas une sandbox système. Il ne bloque à lui seul ni la lecture ni l’écriture dans le dossier principal, et ne limite pas les connexions réseau. Un agent, une commande, un test ou un hook peut accéder à d’autres chemins et services si les permissions du processus l’autorisent.

Les restrictions effectives dépendent du CLI fournisseur, de son mode sandbox, de sa politique d’approbation et des permissions du système. Vérifiez les chemins autorisés en lecture et en écriture, l’accès réseau et les demandes d’approbation avant de lancer l’agent. Dans Réglages → Fournisseurs IA, consultez les options du fournisseur choisi : voir les réglages des fournisseurs IA, notamment le mode sandbox et les approbations de Codex et les options de Gemini. Leurs capacités diffèrent ; l’activation des worktrees n’ajoute pas une protection système universelle.

1. Singularity crée le worktree depuis la branche de base du ticket.
2. L’agent travaille sur la branche dédiée, vérifie son travail et y crée ses commits.
3. À la fin, Singularity réapplique ces commits sur la dernière version de la branche de base.
4. Selon les réglages du board, le résultat est intégré automatiquement ou présenté dans l’onglet Revue.

L’intégration utilise un rebase, pas un merge. Les commits sont rejoués au sommet de la base pour conserver un historique linéaire, sans commit de fusion. Si la base a avancé et qu’un conflit apparaît, l’exécution reste disponible pour le résoudre.

Tickets parallèles et conflits sémantiques

La préqualification peut identifier les dépendances entre tickets actifs : si B dépend de A, B attend son intégration. La file d’intégration ordonne les tickets d’un même projet. Après un rebase sur une base qui a avancé, l’agent doit rejouer les tests concernés et les contrôles du projet, et examiner les tests ajoutés ou modifiés par les autres tickets.

Des tests verts ne garantissent pas l’absence de conflit sémantique. Deux demandes peuvent imposer des règles incompatibles sans conflit Git. Précisez la règle partagée dans les critères d’acceptation et testez les interactions. Une contradiction métier nécessite un arbitrage ; désactivez la fusion automatique pour conserver une revue humaine. Voir l’article sur les tickets parallèles.

Ouvrez Réglages → Git → Worktrees pour piloter l’isolation. Gardez Utiliser les worktrees Git activé pour séparer les dossiers et branches des exécutions. La fusion automatique est distincte : désactivez-la si les exécutions terminées doivent attendre votre approbation dans l’onglet Revue.

Quand l’isolation est désactivée, l’agent écrit directement dans votre arbre de travail. Il n’existe ni dossier ni branche séparés : Singularity n’a donc rien à présenter comme travail isolé dans Revue.

Dans le navigateur, ouvrez la section des worktrees du projet puis le menu concerné. Supprimer le worktree efface son dossier, mais conserve sa branche et ses commits : son historique reste récupérable.

Nettoyer les worktrees supprime aussi leurs références de branche. Cette opération est irréversible. Vérifiez que tout travail utile a été intégré ou conservé ailleurs avant de confirmer.

Le détail d’un ticket affiche, dans Travail, le projet, la branche du worktree et sa branche de base. Dans la vue Git du navigateur, la section Worktrees du projet sépare les worktrees non mergés et mergés, avec leurs compteurs. Dépliez-en un pour voir son dernier commit et ses fichiers modifiés, puis choisissez Fusionner dans main…, Graphe ou Explorer.

Explorer ouvre le worktree dans l’explorateur de fichiers : vous parcourez et ouvrez les fichiers écrits par l’agent pendant qu’il travaille, sans toucher à votre propre copie. Fermez l’exploration pour revenir à votre projet. Si la fusion entre en conflit, voir résoudre un conflit Git.

Depuis le cockpit Git d’un projet, ouvrez l’onglet Hooks pour consulter les hooks détectés dans le dépôt. Ils exécutent les contrôles définis par le projet aux moments prévus par Git.

Si un hook pre-commit échoue, le commit n’a pas eu lieu. Corrigez la cause signalée — formatage, lint ou test, par exemple — puis relancez le commit. Les fichiers peuvent rester modifiés ou indexés : vérifiez leur état dans le cockpit Git.

Le panneau Hooks liste tous les hooks Git possibles ; ceux qui sont installés sont cochés, avec leur nombre de lignes. Singularity détecte Husky (core.hooksPath) et lit les hooks là où Git les exécute réellement. Le menu d’un hook propose Modifier manuellement, Créer un ticket de modification — un agent adapte le hook dans son worktree —, chmod +x pour un hook non exécutable, et Supprimer. Un hook absent peut être créé depuis un modèle.

Dans le composeur de commit, l’indicateur ⚡ suivi d’un nombre annonce les hooks qui tourneront. Leur sortie s’affiche dans un terminal ; si un hook échoue, le commit n’a pas lieu : corrigez la cause puis recommencez.