[2.x] feat: Add cacheVersion setting for global cache invalidation (#8993)

* [2.x] feat: Add cacheVersion setting for global cache invalidation

**Problem**
There was no escape hatch to invalidate all task caches when needed.

**Solution**
Add `Global / cacheVersion` setting that incorporates into the cache key
hash. Changing it invalidates all caches. Defaults to reading system
property `sbt.cacheversion`, or else 0L. When 0L, the hash is identical
to the previous behavior (backward compatible).

Fixes #8992

* [2.x] refactor: Simplify BuildWideCacheConfiguration and add cacheVersion test

- Replace auxiliary constructors with default parameter values
- Add unit test verifying cacheVersion invalidates the cache

* [2.x] fix: Restore auxiliary constructors for binary compatibility

* [2.x] test: Improve cacheVersion scripted test and add release note

- Scripted test now verifies cache invalidation via a counter
  that increments only when the task body actually executes
- Add release note documenting the cacheVersion setting
This commit is contained in:
Dream
2026-04-01 11:23:10 +09:00
committed by GitHub
parent 6d44aca9b1
commit 544f56695a
9 changed files with 152 additions and 12 deletions
+24
View File
@@ -0,0 +1,24 @@
## cacheVersion setting
sbt 2.x caches task results by default. `cacheVersion` provides an escape hatch to invalidate all caches when needed.
### Usage
In `build.sbt`:
```scala
Global / cacheVersion := 1L
```
Or via system property:
```
sbt -Dsbt.cacheversion=1
```
### Details
- Defaults to reading system property `sbt.cacheversion`, or else `0L`
- When `cacheVersion` is `0L`, caching behaves identically to previous versions
- Changing the value invalidates all task caches, forcing recomputation
- The value is incorporated into every cache key via `BuildWideCacheConfiguration`