aggrega cache
Inspecter et entretenir les caches sur disque
Synopsis
aggrega cacheDescription
Inspect and maintain the caches the compiler populates.
status lists cache contents, one element per line, then a summary line.prune reclaims artifact-cache entries no workspace lockfile references.evict trims the compiled-module cache to a size cap, oldest first.clear wipes every cache, including the compiled-module store.Sous-commandes
| Commande | Description |
|---|---|
aggrega cache clear | Efface tous les caches, y compris les modules compilés |
aggrega cache evict | Réduit le cache des modules compilés à une taille maximale, en commençant par les plus anciens |
aggrega cache prune | Supprime les entrées du cache d’artefacts qu’aucun lockfile ne référence |
aggrega cache status | Liste le contenu du cache et un résumé total |
Description de aggrega cache clear
Wipe every cache: the workspace artifact cache (entities, source artifacts,external inputs) and the caches every project on the machine shares (compiledmodules, plugin descriptors, documentation bundles, and the cli plugins addedwhere no workspace was found). This is the total-wipe verb; unlike prune itreclaims the compiled-module cache and the documentation bundles as well.Cleared caches repopulate on the next build, and the documentation bundle onthe next read of the documentation; a cli plugin cleared from the cache isfetched again by adding it again.
Because the wipe is irreversible, clear asks for confirmation before removinganything. Pass --yes to skip the prompt for non-interactive use; without --yeson a non-interactive stdin it refuses rather than blocking on a prompt no onecan answer.Options de aggrega cache clear
| Option | Par défaut | Description |
|---|---|---|
--yes | false | ignore l’invite de confirmation (pour un usage non interactif/CI) |
Description de aggrega cache evict
Trim the compiled-module cache to a size cap by removing theleast-recently-compiled modules first, until the cache total is at or below--max-size. The compiled-module cache is machine-global: every provider guest iscompiled once and reused across every project on the machine, so over time it candominate on-disk cache use.
Unlike prune (which reclaims artifact-cache entries no lockfile references) andclear (which wipes every cache), evict is size-bounded and touches only thecompiled-module cache. Evicted modules recompile on demand on the next build, soeviction loses no irrecoverable state.
--max-size is required and accepts a binary-unit size in the same vocabulary thestatus summary prints — for example 5GiB, "4.5 GiB", or 512MiB — or a bareinteger byte count. The unit suffix is case-insensitive and an optional spacemay separate the number from the unit.
This verb is the on-demand trim, at a cap you give it once. The cache is alsoheld to a standing cap without being asked: every invocation that loads a pluginapplies the `compiled_module_cache.max_bytes` setting (53687091200 bytes, 50 GiB,by default) before it compiles anything, using this same removal order. Use thisverb to reclaim space now or below the standing cap; change the setting to movethe standing cap itself. When the cache already fits the cap, evict reports ano-op and removes nothing.Options de aggrega cache evict
| Option | Par défaut | Description |
|---|---|---|
--max-size | — | taille maximale du cache des modules compilés (par ex. 5GiB, 512MiB ou un nombre d’octets) ; obligatoire |
Description de aggrega cache prune
Remove cache entries whose content digest no workspace lockfile references,retaining every referenced entry. The reference set is the union of thedigests pinned across every lockfile (*.lock) in the workspace, together withthe digests the configuration's plugins.cli list pins, so a cli plugin youadded keeps the bytes it runs from.
Prune acts on the caches whose entries carry a content digest — the workspaceartifact cache (entities, source artifacts, external inputs), theplugin-describe cache and the cli-plugin cache, which holds the cli pluginsadded where no workspace was found — and on the compiled-module cache by reference: a compiledplugin module is reclaimed when no lockfile still references the plugin itbelongs to, and the shared runtime module every plugin depends on is reclaimedonce the last plugin referring to it is pruned. A compiled module that cannot betraced back to a plugin is retained rather than removed on a guess; thatremainder is reclaimed by "aggrega cache evict" or "aggrega cache clear".
Prune needs a pulled workspace: it fails when no lockfile is present.Description de aggrega cache status
List the contents of every cache, one element per line, followed by asummary line of the form "N elements, <human size>". The listing isdeterministic: identical cache state produces byte-identical output.Ce qu’est le cache, et ce qu’il n’est pas
Le cache d’artefacts sous artifact_cache_dir (.aggrega/cache par défaut) contient ce qu’une récupération y a placé : des entités de catalogue et des artefacts sources, chacun stocké sous son type ainsi que la coordonnée et la version auxquelles il a été récupéré, et garanti par un digest que le lockfile enregistre. Ce n’est pas un répertoire de catalogue, et une analyse du catalogue le contourne — le contenu présent dans le cache est donc lu comme une dépendance, par le pin qui le garantit, et jamais comme une entité que vous avez écrite.
La conséquence que vous rencontrerez le plus probablement. Si le cache contient une entité qu’aucun lockfile n’épingle, cette entité est invisible pour un build, et un build qui en a besoin s’arrête en indiquant qu’elle est introuvable. L’arrêt nomme l’entité, de sorte que le pin manquant est identifiable à partir du message.
Lorsque l’entité est une SchemaLibrary qu’atteint un $ref:, chaque commande qui signale la référence comme non résolue fait suivre son signalement d’une ligne remediation: nommant chaque bibliothèque présente dans le cache qu’aucune entrée de lockfile n’épingle et qu’aucun répertoire de catalogue ne fournit, ainsi que l’action qui fonctionne pour cette commande :
aggrega buildetaggrega validate --release <release>lisent le lockfile de la Release ; la ligne nomme doncaggrega pull --release <release>pour résoudre la bibliothèque et enregistrer son entrée.aggrega validatesans argument, etaggrega validate <entity-path>avec ou sans--release, lisent les bibliothèques uniquement depuis les répertoires de catalogue et ne lisent aucun lockfile, si bien qu’aucune entrée enregistrée ne change leur verdict. La ligne le dit, et nommeaggrega pull --release <release>suivi deaggrega validate --release <release>, qui vérifie la Release par rapport à ce que son lockfile épingle.aggrega pull, etaggrega build --auto-pull, en mode hors ligne, ne peuvent ni récupérer la bibliothèque ni enregistrer d’entrée pour elle ; la ligne indique donc d’exécuteraggrega pull --release <release>là où un registre est joignable. En ligne, un pull qui ne trouve la bibliothèque dans aucun répertoire de catalogue ni dans aucun registre qu’il lit n’a aucune entrée à enregistrer.
Chacune de ces lignes propose aussi l’autre solution : écrire la bibliothèque dans un répertoire de catalogue.
Ce qu’il faut exécuter. aggrega pull --release <release> résout l’entité et enregistre son digest, après quoi le même build la trouve. Lorsque l’entité est la vôtre plutôt qu’une dépendance, écrivez-la plutôt sous un répertoire listé dans workspace.catalog_dirs — une analyse lit celui-ci. aggrega cache prune élimine les entrées qu’aucun lockfile ne référence, ce qui est la moitié « rangement » de la même règle.
Pour la structure du cache, le contrat de artifact_cache_dir et la raison pour laquelle un artefact de résolution n’est délibérément pas lisible comme contenu écrit, voir architecture/13-catalog-and-registry.md.
Quels caches appartiennent à ce projet, et lesquels à la machine
Tous les caches sur lesquels agissent ces commandes ne sont pas limités au projet dans lequel vous vous trouvez, et la différence détermine jusqu’où s’étend une récupération d’espace.
À vous seul. Le cache d’artefacts sous artifact_cache_dir — les entités, les artefacts sources et les entrées externes épinglées que ce projet a résolus, ainsi que les instantanés du catalogue publié qu’a lus une importation n’indiquant aucun dossier de catalogue. Y récupérer de l’espace affecte ce projet et rien d’autre.
Partagés par tous les projets Aggrega de cette machine. Le magasin des modules compilés, le magasin des descriptions de plugins, le magasin des bundles de documentation et le magasin des plugins cli. Un guest de provider est compilé une fois et réutilisé par tous les projets, ce qui rend rapide le deuxième build de n’importe quoi ; supprimer une entrée signifie donc que le prochain build de n’importe quel projet de la machine le recompile. Le bundle de documentation — les pages publiées à partir desquelles aggrega explain, les explications d’un éditeur et les ressources de documentation d’un assistant sont lues, et les exemples exécutables que aggrega scaffold --example écrit — est conservé une seule fois par registre et par version, car son contenu ne dépend de rien d’autre : le premier d’entre eux qui le récupère le récupère pour tous les projets, et chaque projet ne le reçoit toutefois qu’une fois que sa propre vérification de signature admet la copie. Rien n’est perdu définitivement — un module supprimé est reconstruit à la demande, et un bundle supprimé est récupéré à nouveau par l’explication ou l’exemple suivant, ou par un serveur d’assistant à son prochain démarrage —, mais le coût retombe sur celui qui construit ensuite, qui n’est peut-être pas vous.
Le magasin des plugins cli contient les octets de chaque plugin cli ajouté avec aggrega plugin add cli dans un dossier qui n’est pas un workspace, de sorte que sa commande s’exécute depuis n’importe quel dossier ; un plugin cli ajouté à l’intérieur d’un workspace conserve plutôt ses octets dans le cache d’artefacts de ce workspace. Contrairement à un module compilé ou à un bundle, un plugin cli dont les octets sont supprimés n’est pas récupéré à nouveau de lui-même : tant que aggrega plugin add cli <name> ne l’a pas ajouté à nouveau, sa commande est absente et chaque commande avertit qu’il n’a pas pu être ajouté, en nommant la commande aggrega plugin add cli qui l’ajoute à nouveau à la version qu’épingle votre configuration.
Les magasins à l’échelle de la machine sont conservés là où chaque plateforme conserve les caches d’un utilisateur : sous Windows dans aggrega\cache à l’intérieur du répertoire que nomme la variable d’environnement LOCALAPPDATA, sous ~/Library/Caches/aggrega sur macOS, et dans un répertoire aggrega à l’intérieur de celui que nomme XDG_CACHE_HOME — ~/.cache/aggrega lorsque XDG_CACHE_HOME n’est pas définie — sur Linux et les autres systèmes Unix. aggrega config init affiche le répertoire sur la machine où il s’exécute. Lorsqu’aucune de ces variables n’est définie, les plugins compilés ne sont conservés que pour l’exécution, et aucun bundle de documentation n’est conservé : une explication indique alors pourquoi son guide pas à pas manque, les ressources de documentation d’un assistant répondent « introuvable », et aggrega scaffold --example refuse, en indiquant qu’aucun répertoire de cache ne se résout ; aggrega plugin add cli exécuté dans un dossier qui n’est pas un workspace refuse également, en indiquant qu’aucun emplacement de cache à l’échelle de la machine ne se résout.
aggrega cache status l’indique par classe plutôt que de le laisser déduire du nom : chaque classe est signalée comme couvrant le workspace ou la machine, et la même portée est signalée pour chaque élément que prune, evict et clear suppriment. evict n’agit que sur le magasin partagé des modules compilés ; prune ne supprime jamais un bundle de documentation ni un instantané de catalogue qu’une importation a lu, puisqu’aucun lockfile ne référence l’un ou l’autre, et signale chacune de ces classes comme non éligible au prune ; prune conserve les octets de chaque plugin cli qu’épingle la liste plugins.cli de votre configuration — dans le magasin des plugins cli comme dans le cache d’artefacts du workspace, avec son entrée de description de plugin — et supprime ceux qu’aucun épinglage ne nomme ; clear agit sur tout, c’est pourquoi il demande confirmation avant de commencer.
Une racine de workspace inutilisable. Lorsque la racine de workspace donnée à la commande est un fichier ou un chemin qui n’existe pas, status, evict et clear n’agissent que sur les magasins à l’échelle de la machine, se terminent comme ils le feraient autrement et le signalent sur la sortie d’erreur standard, dans les termes mêmes par lesquels toute autre commande refuse cette racine :
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (remarque : —workspace-root désigne une racine de workspace qui n’est pas un répertoire ; seuls les caches à l’échelle de la machine sont traités)
Un chemin qui n’existe pas affiche which cannot be used: et la raison à la place de which is not a directory:. prune s’arrête en revanche, puisqu’il a besoin des lockfiles du workspace.
Ceci s’applique quel que soit l’endroit d’où l’opération est invoquée, pas seulement dans un terminal. Les mêmes opérations sont accessibles depuis une session d’éditeur et depuis l’appel d’outil d’un assistant, et leurs réponses indiquent la même portée pour la même raison. Lorsqu’un assistant peut les invoquer en votre nom, voir aggrega mcp.
Un lien dans le cache d’artefacts
Le répertoire du cache d’artefacts est le seul endroit depuis lequel tout ce qui se trouve dans le cache est lu, dans lequel il est écrit et duquel il est supprimé — aussi bien le .aggrega/cache par défaut qu’un répertoire nommé par artifact_cache_dir qui remonte au-delà de la racine du workspace (../shared-cache). Tout ce qui s’y trouve et qui est un lien symbolique menant hors de ce répertoire — l’un des répertoires propres du cache, comme .aggrega/cache/inputs, ou un fichier à l’intérieur de l’un d’eux — n’est ni lu, ni écrit, ni supprimé à travers ce lien, même lorsque le lien mène à un autre répertoire du même workspace. Ce qu’une écriture peut atteindre sous le répertoire du cache est exactement ce qu’une suppression peut atteindre.
- Un pull, un build et toute autre opération qui écrit dans le cache s’arrêtent avec
E0320, en nommant le lien et l’endroit où il mène, et n’écrivent rien. status,pruneetclearne listent rien à travers un tel lien. Lorsque l’un des répertoires propres du cache est le lien,statuss’arrête avecE0321, et unpruneou unclears’arrête avecE0320avant de lister ou de supprimer quoi que ce soit — ainsi rien de ce vers quoi pointe le lien n’est supprimé, et le lien reste en place. Lorsque c’est un fichier à l’intérieur de l’un d’eux qui est le lien, les trois s’arrêtent avecE0321.- Un build, un pull et toute autre opération qui lit le cache s’arrêtent avec
E0321plutôt que de lire des octets conservés ailleurs, même lorsque ces octets correspondraient au digest que le lockfile enregistre. - Un lien qui reste à l’intérieur du répertoire du cache est suivi. Lorsque l’un des répertoires propres du cache est un lien vers un autre répertoire à l’intérieur du répertoire du cache, ce répertoire appartient au cache :
statusliste ce qui s’y trouve,pruney supprime, etclearle vide, conserve le lien et signale les octets qu’il y a supprimés.
Le répertoire du cache lui-même. Un artifact_cache_dir écrit à l’intérieur de la racine du workspace — y compris la valeur par défaut — peut lui-même être un lien vers un autre répertoire du workspace, et le cache est alors conservé là où mène le lien. Un lien qui mène hors du workspace est refusé : quelle que soit l’opération qui le rencontre, elle s’arrête avec E0321 ou E0320, en nommant le lien, avant que quoi que ce soit ne soit lu ou écrit à travers lui. Un répertoire écrit en remontant au-delà de la racine du workspace est respecté là où il mène, même lorsqu’il est lui-même un lien.
Supprimez le lien et refaites un pull pour remplir le cache sur place. Pour conserver le cache ailleurs, définissez artifact_cache_dir sur ce répertoire, écrit relativement à la racine du workspace, plutôt que de créer un lien vers lui : un répertoire nommé là est lu et écrit là où il mène. Les magasins à l’échelle de la machine ne sont rattachés à aucun workspace ; un magasin que vous conservez ailleurs au moyen d’un lien est listé, nettoyé et vidé là où mène le lien, et clear conserve le lien. La frontière du workspace énonce la règle dans son ensemble.
Voir aussi
aggrega-pull— résout les dépendances d’une Release dans le lockfile et le cache.aggrega-config— où s’écriventartifact_cache_diret les autres paramètres du cache.