aggrega cache
Inspecionar e manter as caches em disco
Sinopse
aggrega cacheDescrição
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.Subcomandos
| Comando | Descrição |
|---|---|
aggrega cache clear | Apagar todas as caches, incluindo os módulos compilados |
aggrega cache evict | Reduzir a cache de módulos compilados até um limite de tamanho, começando pelos mais antigos |
aggrega cache prune | Remover entradas da cache de artefactos que nenhum lockfile referencia |
aggrega cache status | Listar o conteúdo da cache e um resumo total |
Descrição 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.Flags de aggrega cache clear
| Flag | Predefinição | Descrição |
|---|---|---|
--yes | false | ignorar o pedido de confirmação (para uso não interativo/em CI) |
Descrição 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.Flags de aggrega cache evict
| Flag | Predefinição | Descrição |
|---|---|---|
--max-size | — | limite de tamanho da cache de módulos compilados (p. ex., 5GiB, 512MiB ou um número de bytes); obrigatório |
Descrição 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.Descrição 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.O que a cache é e o que não é
A cache de artefactos em artifact_cache_dir (.aggrega/cache por predefinição) contém o que uma obtenção lá colocou: entidades de catálogo e artefactos de origem, cada um guardado sob o seu tipo e a coordenada e a versão em que foi obtido, e garantido por um digest que o lockfile regista. Não é um diretório de catálogo, e uma análise do catálogo passa-lhe ao lado — pelo que o conteúdo que está na cache é lido como uma dependência, através da fixação que o garante, e nunca como uma entidade escrita pelo utilizador.
A consequência que tem mais probabilidade de encontrar. Se a cache contém uma entidade que nenhum lockfile fixa, essa entidade é invisível para uma compilação, e uma compilação que precise dela para, indicando que não foi encontrada. A paragem nomeia a entidade, pelo que a fixação em falta é identificável a partir da mensagem.
Quando a entidade é uma SchemaLibrary alcançada por um $ref:, cada comando que reporta a referência como não resolvida faz seguir o relatório de uma linha remediation: que nomeia cada biblioteca que a cache contém e que nenhuma entrada de lockfile fixa nem nenhum diretório de catálogo fornece, e a ação que resulta para esse comando:
aggrega buildeaggrega validate --release <release>leem o lockfile da Release, pelo que a linha nomeiaaggrega pull --release <release>para resolver a biblioteca e registar a sua entrada.aggrega validatesem argumento, eaggrega validate <entity-path>com ou sem--release, leem bibliotecas apenas dos diretórios de catálogo e não leem nenhum lockfile, pelo que nenhuma entrada registada altera o seu veredicto. A linha di-lo e nomeiaaggrega pull --release <release>seguido deaggrega validate --release <release>, que verifica a Release em relação ao que o seu lockfile fixa.aggrega pull, eaggrega build --auto-pull, no modo sem ligação não conseguem obter a biblioteca nem registar uma entrada para ela, pelo que a linha indica que se executeaggrega pull --release <release>onde for possível chegar a um registo. Com ligação, um pull que não encontra a biblioteca em nenhum diretório de catálogo nem em nenhum registo que lê não tem nenhuma entrada a registar.
Cada uma dessas linhas oferece também o outro caminho: escrever a biblioteca num diretório de catálogo.
O que executar. aggrega pull --release <release> resolve a entidade e regista o seu digest, após o que a mesma compilação a encontra. Quando a entidade é sua e não uma dependência, escreva-a antes num diretório listado em workspace.catalog_dirs — uma análise lê esse diretório. aggrega cache prune limpa as entradas que nenhum lockfile referencia, que é a metade de arrumação da mesma regra.
Para a estrutura da cache, o contrato de artifact_cache_dir e o motivo pelo qual um artefacto de resolução não é deliberadamente legível como conteúdo escrito, consulte architecture/13-catalog-and-registry.md.
Que caches pertencem a este projeto e quais pertencem à máquina
Nem todas as caches sobre as quais estes comandos atuam estão circunscritas ao projeto em que o utilizador se encontra, e a diferença decide até onde chega uma recuperação de espaço.
Só suas. A cache de artefactos em artifact_cache_dir — as entidades, os artefactos de origem e as entradas externas fixadas que este projeto resolveu, e os snapshots do catálogo publicado que uma importação que não indica nenhuma pasta de catálogo leu. Recuperar espaço nela afeta este projeto e mais nenhum.
Partilhadas por todos os projetos Aggrega nesta máquina. O armazenamento de módulos compilados, o armazenamento de descrições de plugins, o armazenamento de pacotes de documentação e o armazenamento de plugins cli. Um guest de fornecedor é compilado uma vez e reutilizado por todos os projetos, o que torna rápida a segunda compilação de qualquer coisa, pelo que remover uma entrada significa que a próxima compilação de qualquer projeto na máquina o volta a compilar. O pacote de documentação — as páginas publicadas a partir das quais aggrega explain, as explicações de um editor e os recursos de documentação de um assistente são lidos, e os exemplos executáveis que aggrega scaffold --example escreve — é guardado uma vez por registo e versão, porque o seu conteúdo não depende de mais nada: aquele que o obtiver primeiro obtém-no para todos os projetos, e cada projeto só o recebe depois de a sua própria verificação de assinatura admitir a cópia. Nada se perde definitivamente — um módulo removido é reconstruído quando necessário, e um pacote removido é obtido novamente pela explicação ou pelo exemplo seguinte, ou por um servidor de assistente quando voltar a arrancar — mas o custo recai sobre quem compilar a seguir, que pode não ser o utilizador.
O armazenamento de plugins cli guarda os bytes de cada plugin cli adicionado com aggrega plugin add cli numa pasta que não é um espaço de trabalho, pelo que o seu comando é executado a partir de qualquer pasta; um plugin cli adicionado dentro de um espaço de trabalho guarda, em vez disso, os seus bytes na cache de artefactos desse espaço de trabalho. Ao contrário de um módulo compilado ou de um pacote, um plugin cli cujos bytes são removidos não volta a ser obtido por si só: até que aggrega plugin add cli <name> o volte a adicionar, o seu comando está em falta e todos os comandos avisam que não foi possível adicioná-lo, nomeando o comando aggrega plugin add cli que o volta a adicionar na versão fixada pela configuração.
Os armazenamentos de toda a máquina são guardados onde cada plataforma guarda as caches de um utilizador: no Windows em aggrega\cache dentro do diretório que a variável de ambiente LOCALAPPDATA nomeia, em ~/Library/Caches/aggrega no macOS, e num diretório aggrega dentro daquele que XDG_CACHE_HOME nomeia — ~/.cache/aggrega quando XDG_CACHE_HOME não está definida — no Linux e nos outros sistemas Unix. aggrega config init imprime o diretório na máquina em que é executado. Quando nenhuma dessas variáveis está definida, os plugins compilados são guardados apenas durante a execução e nenhum pacote de documentação é guardado: uma explicação indica então porque falta o seu percurso guiado, os recursos de documentação de um assistente respondem que não foram encontrados, e aggrega scaffold --example recusa, indicando que nenhum diretório de cache é resolvido; aggrega plugin add cli executado numa pasta que não é um espaço de trabalho também recusa, indicando que nenhuma localização de cache de toda a máquina é resolvida.
aggrega cache status indica isto por classe em vez de deixar que seja deduzido a partir do nome: cada classe é reportada como abrangendo o espaço de trabalho ou a máquina, e o mesmo alcance é reportado para cada elemento que prune, evict e clear removem. evict atua apenas sobre o armazenamento partilhado de módulos compilados; prune nunca remove um pacote de documentação nem um snapshot de catálogo que uma importação leu, já que nenhum lockfile referencia nenhum dos dois, e reporta cada uma dessas classes como não elegível para prune; prune mantém os bytes de cada plugin cli que a lista plugins.cli da configuração fixa — tanto no armazenamento de plugins cli como na cache de artefactos do espaço de trabalho, juntamente com a respetiva entrada de descrição de plugin — e remove os que nenhuma fixação nomeia; clear atua sobre tudo, e é por isso que pergunta antes de começar.
Uma raiz de workspace que não pode ser usada. Quando a raiz de workspace indicada ao comando é um ficheiro ou um caminho que não existe, status, evict e clear atuam apenas sobre os armazenamentos de toda a máquina, terminam como terminariam de outro modo e indicam-no na saída de erro padrão, com as mesmas palavras com que qualquer outro comando recusa essa raiz:
note: —workspace-root names the workspace root
"<root>", which is not a directory:<root>; only the machine-wide caches are acted on (nota: —workspace-root nomeia uma raiz de workspace que não é um diretório; atua-se apenas sobre as caches de toda a máquina)
Um caminho que não existe apresenta which cannot be used: e o motivo em vez de which is not a directory:. Já prune para, uma vez que precisa dos lockfiles do workspace.
Isto aplica-se seja qual for o local a partir do qual a operação é invocada, não apenas num terminal. As mesmas operações estão acessíveis a partir de uma sessão de editor e da chamada de ferramenta de um assistente, e as suas respostas indicam o mesmo alcance pela mesma razão. Quando um assistente as pode invocar em nome do utilizador, consulte aggrega mcp.
Uma ligação na cache de artefactos
O diretório da cache de artefactos é o único local a partir do qual tudo o que está na cache é lido, escrito e removido — tanto o .aggrega/cache predefinido como um diretório que artifact_cache_dir nomeie saindo da raiz do espaço de trabalho (../shared-cache). Tudo o que nele seja uma ligação simbólica que sai desse diretório — um dos próprios diretórios da cache, como .aggrega/cache/inputs, ou um ficheiro dentro de um deles — não é lido, escrito nem removido através dela, mesmo quando a ligação leva a outro diretório do mesmo espaço de trabalho. O que uma escrita pode alcançar sob o diretório da cache é exatamente o que uma remoção pode alcançar.
- Um pull, uma compilação e todas as outras operações que escrevem na cache param com
E0320, nomeando a ligação e o destino para onde leva, e não escrevem nada. status,pruneeclearnão listam nada através de uma ligação dessas. Quando um dos próprios diretórios da cache é a ligação,statuspara comE0321, e umpruneou umclearpara comE0320antes de listar ou remover o que quer que seja — pelo que nada daquilo para que a ligação aponta é removido, e a ligação fica onde está. Quando um ficheiro dentro de um deles é a ligação, os três param comE0321.- Uma compilação, um pull e todas as outras operações que leem a cache param com
E0321em vez de lerem bytes guardados noutro local, mesmo quando esses bytes corresponderiam ao digest que o lockfile regista. - Uma ligação que permanece dentro do diretório da cache é seguida. Quando um dos próprios diretórios da cache é uma ligação para outro diretório dentro do diretório da cache, esse diretório é da cache:
statuslista o que lá está,pruneremove a partir daí, eclearesvazia-o, mantém a ligação e reporta os bytes que lá removeu.
O próprio diretório da cache. Um artifact_cache_dir escrito dentro da raiz do espaço de trabalho — incluindo o predefinido — pode ser ele próprio uma ligação para outro diretório do espaço de trabalho, e a cache é então guardada para onde a ligação leva. Uma que saia do espaço de trabalho é recusada: qualquer operação que a encontre para com E0321 ou E0320, nomeando a ligação, antes de algo ser lido ou escrito através dela. Um diretório escrito saindo da raiz do espaço de trabalho é respeitado para onde leva, mesmo quando é ele próprio uma ligação.
Remova a ligação e faça novamente pull para preencher a cache no local. Para guardar a cache noutro sítio, defina artifact_cache_dir com esse diretório, escrito em relação à raiz do espaço de trabalho, em vez de criar uma ligação para ele: um diretório nomeado aí é lido e escrito para onde leva. Os armazenamentos de toda a máquina não estão sujeitos a nenhum espaço de trabalho; um que se guarde noutro local através de uma ligação é listado, limpo e esvaziado para onde a ligação leva, e clear mantém a ligação. A fronteira do espaço de trabalho enuncia a regra completa.
Ver também
aggrega-pull— resolver as dependências de uma Release para o lockfile e a cache.aggrega-config— onde se escrevemartifact_cache_dire as outras definições da cache.