diff --git a/crates/uv-cache/src/lib.rs b/crates/uv-cache/src/lib.rs index a91b9cdef..615760788 100644 --- a/crates/uv-cache/src/lib.rs +++ b/crates/uv-cache/src/lib.rs @@ -764,7 +764,7 @@ pub enum CacheBucket { impl CacheBucket { fn to_str(self) -> &'static str { match self { - Self::SourceDistributions => "sdists-v4", + Self::SourceDistributions => "sdists-v5", Self::FlatIndex => "flat-index-v1", Self::Git => "git-v0", Self::Interpreter => "interpreter-v2", diff --git a/crates/uv/tests/it/cache_prune.rs b/crates/uv/tests/it/cache_prune.rs index f103e0180..251a3052d 100644 --- a/crates/uv/tests/it/cache_prune.rs +++ b/crates/uv/tests/it/cache_prune.rs @@ -328,7 +328,7 @@ fn prune_stale_revision() -> Result<()> { ----- stderr ----- DEBUG uv [VERSION] ([COMMIT] DATE) Pruning cache at: [CACHE_DIR]/ - DEBUG Removing dangling source revision: [CACHE_DIR]/sdists-v4/[ENTRY] + DEBUG Removing dangling source revision: [CACHE_DIR]/sdists-v5/[ENTRY] DEBUG Removing dangling cache archive: [CACHE_DIR]/archive-v0/[ENTRY] Removed 8 files ([SIZE]) "###); diff --git a/docs/concepts/cache.md b/docs/concepts/cache.md index b77af6c93..5403d59e2 100644 --- a/docs/concepts/cache.md +++ b/docs/concepts/cache.md @@ -158,16 +158,13 @@ release contains a breaking change to the cache format, uv will not attempt to r an incompatible cache bucket. For example, uv 0.4.13 included a breaking change to the core metadata bucket. As such, the bucket -version was increased from v12 to v13. +version was increased from v12 to v13. Within a cache version, changes are guaranteed to be both +forwards- and backwards-compatible. -Within a cache version, changes are guaranteed to be forwards-compatible, but _not_ -backwards-compatible. +Since changes in the cache format are accompanied by changes in the cache version, multiple versions +of uv can safely read and write to the same cache directory. However, if the cache version changed +between a given pair of uv releases, then those releases may not be able to share the same +underlying cache entries. -For example, uv 0.4.8 can read cache entries written by uv 0.4.7, but uv 0.4.7 cannot read cache -entries written by uv 0.4.8. As a result, it's safe to share a cache directory across multiple uv -versions, as long as those versions are strictly increasing over time, as is common in production -and development environments. - -If you intend to use multiple uv versions on an ongoing basis, we recommend using separate caches -for each version, as (e.g.) a cache populated by uv 0.4.8 may not be usable by uv 0.4.7, despite the -cache _versions_ remaining unchanged between the releases. +For example, it's safe to use a single shared cache for uv 0.4.12 and uv 0.4.13, though the cache +itself may contain duplicate entries in the core metadata bucket due to the change in cache version.