pub const CACHES_CLEAR_LONG: &str = "\
Empty one manager's cache, or every one of them. What is about to go is listed and \
sized first, and unless `--yes` answers for you, it asks.
This is a convenience, not automation. No scheduler, no Git hook and no `devp run` \
will ever clear a cache — this only runs when you type it.
Wherever the manager ships its own subcommand, that is what runs: `npm cache clean \
--force`, `pnpm store prune`, `go clean -modcache`. The manager knows what is still \
referenced, which a directory delete cannot work out, and its own bookkeeping stays \
consistent. cargo, gradle, vcpkg and hex ship nothing equivalent, so those \
are cleared by removing the directory this command resolved and sized — never a string \
handed to a shell.
Maven is reported and never cleared. `~/.m2/repository` is an install target as \
well as a download cache — `mvn install:install-file` puts artifacts there that no \
remote can hand back — so dev-prune sizes it and prints `rm -rf ~/.m2/repository` \
for you to run. `clear maven` says so and stops; `clear all` skips it.
The target takes a list: `devp caches clear npm,uv,pip` empties exactly those three \
and nothing else — a one-time whitelist, no configuration involved. The mirror image \
is `devp caches clear all --except npm,uv`: everything goes except the names given, \
for the day one cache is the only one worth keeping warm. `--except` only makes sense \
with `all` — a list already says exactly what to clear — and a container engine never \
appears in either: naming an engine alone is the consent to touch it.
Two flags narrow what `all` means, so you do not have to pick the caches by hand. \
`--over-cap` keeps only the managers that have outgrown the ceiling you set in \
`cache_max_gb`; with no cap set anywhere it clears nothing and says so. `--unused` keeps \
only the managers that no registered repository uses — a cache with nothing behind it \
was filled for projects that are not on this disk any more. It counts only repositories \
dev-prune knows about, so `devp link` anything you keep outside the registry first, and \
it refuses to run at all when there are no registered repositories to check against.
Nothing else in a cache is lost; every manager re-downloads what it needs. What it costs \
is time, in every project on the machine, on the next install and the next `devp \
restore`. The freed size reported afterwards is measured rather than assumed, because \
a `prune` keeps what is still in use.
`--include-volumes` belongs to a container engine named alone, and only docker and \
podman can honour it: they are the engines whose `volume ls` can narrow to volumes \
nothing uses. After the narrow steps run, the unused volumes are listed by name and you \
type the numbers of the ones to delete; each pick is one unforced `volume rm`, and an \
empty answer keeps them all. dev-prune never runs `volume prune`. Because a volume \
holds the only copy of what is in it, the flag refuses `--yes`, `--json` and a piped \
stdin: nothing unattended can reach it, and that is the point. The one unattended \
spelling is `--include-volumes --dry-run`, which deletes nothing: it lists the unused \
volumes by name with the command to paste, so a script or an agent can prepare \
everything and a person runs the final command at a terminal. The pick list also arms \
only within ten minutes of a completed dry run for that engine: outside the window \
the real command runs the dry run instead, says so, and the same line typed again \
within ten minutes goes through. What the picks free is then counted on `devp stats`, \
which a `volume rm` typed straight at the engine would not be.";