# Réglages de projet — explication ## De quoi s'agit-il ? Un projet peut garder un `.turbo-js/settings.toml` à côté de son code, disant quel thème utiliser et s'il faut enregistrer les fichiers automatiquement. Cette page traite des décisions contenues dans cette phrase : pourquoi le fichier n'est cherché qu'à un seul endroit, pourquoi le créer est une entrée de menu plutôt que quelque chose qui arrive tout seul, et pourquoi la sauvegarde automatique fonctionne comme elle le fait. ## Pourquoi le dossier n'est pas cherché vers le haut `package.json` est trouvé en remontant depuis le fichier ouvert jusqu'à en croiser un, et le serveur de langage fait exactement cela. Le fichier de réglages, délibérément, non : il n'est cherché que dans le répertoire de travail. La remontée est juste pour `package.json` parce qu'un paquet a une frontière réelle : le fichier est au-dessus de vous ou il n'y est pas, et être dans un paquet est un fait à propos du code. « Le projet » n'est pas un fait à propos du code. C'est l'endroit où vous avez décidé de travailler, et la même arborescence est plusieurs projets selon ce que vous y faites — le `services/api` d'un monorepo est un projet quand vous travaillez sur l'API, et une partie d'un plus grand le reste du temps. Une remontée ferait aussi agir le réglage à distance. Vous ouvrez un fichier, et les couleurs de l'éditeur changent à cause d'un fichier trois dossiers plus haut dont vous ignoriez l'existence. Toute explication de ce comportement commence par « eh bien, il cherche vers le haut », alors que la règle qu'on préfère pouvoir énoncer est celle qui est maintenant vraie : **le projet est le dossier depuis lequel vous avez lancé l'éditeur.** Le coût est réel et mérite d'être nommé. Lancez l'éditeur depuis un sous-dossier et le thème du projet ne s'applique pas. La réponse est de lancer depuis la racine du projet, là où vous feriez `npm install` et `git` de toute façon. ## Pourquoi créer le fichier est une entrée de menu L'autre solution était tentante : à la première fois qu'on choisit un thème, écrire `.turbo-js/settings.toml` pour que le choix persiste. Tout éditeur qui stocke un état d'espace de travail fait quelque chose d'approchant. Elle a été écartée parce qu'elle dépose un dossier dans le dépôt de quelqu'un comme effet de bord d'un essai de couleur. L'utilisateur est à un `git status` d'une modification qu'il n'a pas faite, dans un projet qui n'est peut-être pas le sien, éventuellement en pleine revue. Un thème choisi pour être regardé dix secondes ne doit rien laisser derrière lui. Le fichier n'est donc créé que par **Options ▸ Create project settings**, et son existence signifie quelque chose : ce projet a des réglages, exprès. C'est aussi ce qui rend la règle d'écriture simple à énoncer — **le thème est écrit dans le fichier quand le fichier existe, et pas autrement** — sans nulle part une case « voulez-vous vous en souvenir ? ». ## Pourquoi le thème est réécrit sur place plutôt que réencodé Une fois le fichier créé, choisir un thème le réécrit. Sérialiser la structure `Settings` vers du TOML ferait quatre lignes et supprimerait tous les commentaires du fichier. Cela compte plus ici qu'ailleurs, parce que ce fichier est *fait* pour être édité à la main. C'est la raison d'être de la coloration TOML dans l'éditeur ; le fichier créé est surtout des commentaires expliquant les clés ; une équipe y ajoutera ses propres commentaires disant pourquoi elle a choisi ce qu'elle a choisi. Tout perdre à la première tentative d'un autre thème serait une suppression silencieuse et surprenante de ce que quelqu'un a écrit. La réécriture trouve donc la ligne `theme` dans la table `[editor]` et change la valeur entre le `=` et un éventuel commentaire de fin de ligne. Tout le reste du fichier revient octet pour octet. Cela fait une quarantaine de lignes au lieu de quatre, et c'est la différence entre un fichier où l'on peut mettre des choses et un fichier qui les mange. ## Pourquoi la sauvegarde automatique attend une pause Trois déclencheurs ont été envisagés. **À intervalle fixe** est le plus simple et il est faux : il écrit au milieu d'une modification. La moitié d'un identifiant renommé atteint le disque, un observateur de fichiers relance les tests, et une suite échoue sur du code qui n'a jamais été l'intention de personne. **À la sortie de la fenêtre** n'écrit jamais pendant qu'on travaille, ce qui semble prudent et signifie que ce qui est sur le disque peut avoir une heure de retard sur ce qui est à l'écran — précisément quand cela compte, puisque la raison de vouloir l'autosave est en général un outil qui surveille le fichier. **Après une pause dans la frappe** est ce sur quoi les autres éditeurs et celui-ci se sont arrêtés. Deux secondes, c'est assez long pour qu'une pause de réflexion ne soit pas une écriture, assez court pour qu'un `node --test` relancé suive de près une modification. Une série de frappes fait une écriture, pas une par touche. Il y a une seule échéance pour tout l'éditeur plutôt qu'une par fenêtre, parce que « vous avez cessé de taper » est un seul événement. Une échéance par fenêtre enregistrerait le fichier que vous avez quitté à un moment différent de celui que vous avez sous les yeux, ce que personne ne pourrait observer et qui fait davantage d'état à maintenir juste. ## Pourquoi l'échéance est vérifiée, le minuteur ne faisant que pousser C'est le même piège que l'annonce au serveur de langage et que les redessins de terminal ont rencontré, et il vaut d'être énoncé une fois de plus parce qu'il reviendra. L'éditeur est bloqué dans `PollEvent`. Pour remarquer une échéance alors que rien ne se passe, il faut le réveiller, et le seul moyen de le réveiller depuis un minuteur est `PostEvent` — qui **jette** les événements quand sa file est pleine. Le minuteur n'est donc pas ce qui décide. L'échéance est un état, vérifié en tête de chaque tour de boucle, exactement comme `announceOpenDocuments` vérifie si le serveur de langage est prêt. Le seul rôle du minuteur est de garantir qu'un tour ait lieu. Une poussée perdue coûte une sauvegarde en retard jusqu'à la frappe ou au clic suivant ; un design où le minuteur enregistrerait lui-même la perdrait tout court. ## Pourquoi une sauvegarde automatique en échec n'ouvre pas de dialogue Une sauvegarde que personne n'a demandée ne doit pas interrompre par une fenêtre modale, et une modale qui revient toutes les deux secondes parce qu'un fichier est en lecture seule est pire que le problème qu'elle signale. Cela va donc dans la barre d'état, et l'échéance est effacée *avant* la tentative d'écriture : un fichier qui ne peut pas être écrit est essayé une fois par modification, et non indéfiniment. ## Pourquoi la coloration TOML réutilise les classes existantes Ajouter `syntax.tomlkey` et compagnie aurait signifié que tous les thèmes — y compris ceux écrits par les utilisateurs — auraient silencieusement échoué à colorer le TOML jusqu'à leur mise à jour. Les classes déjà présentes conviennent : un en-tête de table nomme une structure, il se lit donc comme un type ; une clé nomme une chose, elle se lit donc comme un identifiant ; `true` et `false` sont des constantes parce que c'est ce qu'elles sont. Le résultat est que tout thème qui a jamais fonctionné colore le TOML correctement, sans modification et sans nouvelle clé. Le scanner est écrit à la main pour la même raison que l'émulateur de terminal — le TOML est un langage petit et entièrement spécifié, et c'est un fichier contre une troisième dépendance. ## Liens avec le reste - Les clés exactes et leurs valeurs par défaut : [Référence des réglages de projet](../reference/project-settings.md) - En mettre en place : [Donner ses propres réglages à un projet](../how-to/configure-a-project.md) - L'autre fichier TOML que lit l'éditeur : [Format des fichiers de thème](../reference/themes.md) - Où `settings` se situe parmi les paquets : [Architecture](architecture.md)