Add documentation for cache clearing

docs/concepts/cache.md

@@ -22,13 +22,39 @@ uv's cache is designed to be thread-safe and append-only, and thus robust to mul
 readers and writers. uv applies a file-based lock to the target virtual environment when installing,
 to avoid concurrent modifications across processes.
 
-Note that it's _not_ safe to modify the uv cache directly (e.g., `uv cache clean`) while other uv
-commands are running, and _never_ safe to modify the cache directly (e.g., by removing a file or
-directory).
+Note that it's _not_ safe to modify the uv cache (e.g., `uv cache clean`) while other uv commands are
+running, and _never_ safe to modify the cache directly (e.g., by removing a file or directory).
 
 If you're running into caching issues, uv includes a few escape hatches:
 
 - To force uv to revalidate cached data for all dependencies, run `uv pip install --refresh ...`.
 - To force uv to revalidate cached data for a specific dependency, run, e.g., `uv pip install --refresh-package flask ...`.
 - To force uv to ignore existing installed versions, run `uv pip install --reinstall ...`.
-- To clear the global cache entirely, run `uv cache clean`.
+
+## Clearing the cache
+
+uv provides a few different mechanisms for removing entries from the cache:
+
+- `uv cache clean` removes _all_ cache entries from the cache directory, clearing it out entirely.
+- `uv cache clean ruff` removes all cache entries for the `ruff` package, useful for invalidating the cache for a
+   single or finite set of packages.
+- `uv cache prune` removes all _unused_ cache entries. For example, the cache directory may contain entries created in
+   previous uv versions that are no longer necessary and can be safely removed. `uv cache prune` is safe to
+   run periodically, to keep the cache directory clean.
+
+## Caching in continuous integration
+
+It's common to cache package installation artifacts in continuous integration environments (like GitHub Actions or
+GitLab CI) to speed up subsequent runs.
+
+By default, uv caches both the wheels that it builds from source and the pre-built wheels that it downloads directly,
+to enable high-performance package installation.
+
+However, in continuous integration environments, persisting pre-built wheels may be undesirable. With uv, it turns out
+that it's often faster to _omit_ pre-built wheels from the cache (and instead re-download them from the registry on each
+run). On the other hand, caching wheels that are built from source tends to be worthwhile, since the wheel building
+process can be expensive, especially for extension modules.
+
+To support this caching strategy, uv provides a `uv cache prune --ci` command, which removes all pre-built wheels from
+the cache but retains any wheels that were built from source. We recommend running `uv cache prune --ci` at the end of
+your continuous integration job to ensure maximum cache efficiency.