kunobi-ninja/kache v1.0.0 on GitHub

Kache 1.0 lets you share compiler outputs through an OCI registry, recover disk space from copied target directories, and integrate the CLI through versioned JSON. The 1.x series now carries compatibility guarantees for documented commands, configuration, JSON, and public Rust APIs.

Install or upgrade

cargo install kache --version 1.0.0 --locked
kache init

kache init previews the setup before applying it. Then use Cargo as usual in your project. Prebuilt packages and other installation methods are also available.

Highlights

Use your OCI registry as a remote cache. Authenticate with docker login, oras login, or CI credentials.
Keep fewer copies of the same outputs. Copied target files can share disk blocks with the cache on filesystems that support cloning.
Automate setup and reporting. CLI and configuration compatibility now have a 1.x contract; JSON output has an explicit schema version.

Added

OCI: configure a dedicated registry repository as a remote. Docker credential helpers are supported, and credentials refresh when authorization expires. #1427, #1428 by @jleni.
```
[cache.remote]
type = "oci"
repository = "ghcr.io/my-org/kache-cache"
prefix = "artifacts"
```
OCI pull-request jobs stay read-only. Use a single publisher when merged build metadata must retain every update: registries do not guarantee conditional tag writes. Setup and credentials.
Target storage: kache targets share previews files that match cached blobs; kache targets share --apply replaces those copies with filesystem clones. Paths, permissions, and modification times are preserved. The daemon runs short sharing passes while idle by default. #1358 by @jleni.
Disk recovery: discover sibling worktree targets and, when enabled, prune unused build units before removing idle targets under disk pressure on Unix. Set cache.auto_recover_min_free_bytes to enable it; the default is off. kache targets previews the next pass. #1356, #1357 by @jleni.
Rust documentation: cache supported Unix rustdoc invocations, including the search index. Cargo 1.99 and Windows pass through; caching currently requires the older unstable merge interface. Compatibility and setup. #1360 by @jleni.

Changed

CLI: inspect detailed reports with kache stats --full, investigate misses with kache explain, and reclaim disk space with kache clean. Existing aliases remain available. Setup shows one plan confirmation, plus a separate confirmation when replacing another Cargo wrapper. #1359, #1385, #1417 by @jleni.
JSON: setup, reports, help, version, and command failures use a versioned envelope. Check schema_version and success; progress goes to stderr. Explicit --format json keeps the standalone report format. #1417 by @jleni.
Monitor and diagnosis: kache monitor opens on Now, showing cache usage, savings, and recent builds. kache explain identifies cross-checkout differences and recommends path mapping when the recorded inputs support it. Lifetime savings survive event-log rotation. #1414, #1398, #1389 by @jleni.
Compiler shims: discover versioned drivers such as clang-19 and gcc-13, and remove their links when the compiler disappears. #1399, #1402 by @jleni, with the versioned-driver contribution by @glebpom.

Performance

These improvements ship without changing performance defaults.

External target directories: reuse workspace input predictions when CARGO_TARGET_DIR is outside the checkout. In six paired eza release-build runs at default settings, warm restores went from 1.050 s to 0.598 s, a 43% reduction, with the same hits and compiler counts. This measures that workload and target layout, rather than a general build-speed claim. #1429 by @jleni.
Target seeding: copy more eligible registry units before the existing deadline, reducing subsequent rebuilds. A measured 53-crate workspace on btrfs completed a full seed in 0.58 s, down from 31.5 s. These are seeding times with a warm page cache, not whole-build times. #1381 by @AlJohri.
S3 synchronization: scoped kache sync --pull overlaps crate listings within the existing concurrency limit, so dependencies no longer wait for serial discovery. #1431 by @jleni.
Remote requests: known cache packs download without a preliminary HEAD, cutting an unindexed exact-key hit from two requests to one. OCI embeds small JSON metadata in manifests and caches authorization, reducing warm metadata reads from four requests to one. #1432, #1428 by @jleni.

Fixed

Cache statistics: compare registered blob bytes with the cache limit; show logical size and deduplication savings separately. #1436 by @xrl.
Hermetic build scripts: declaring OUT_DIR no longer prevents reuse across target directories. This requires the existing opt-in KACHE_BUILD_SCRIPT_HERMETIC=1. #1437 by @AlJohri.
Build-script outputs: prevent stale replay of absolute inputs across checkouts, restore named libraries outside OUT_DIR, and preserve symlinks that stay inside it. Reports separate script execution from wrapper overhead and retain the execution cost saved by hits. #1425, #1418, #1434 by @jleni; #1365 by @AlJohri.
Native restores: editing a restored C/C++ object in place no longer changes the cached blob. #1423 by @jleni.
Toolchains and cleanup: reread rustc's version after a rustup update and release Cargo and target-probe locks after use. #1407, #1386 by @jleni; #1364 by @kikijiki.

Upgrading to 1.0

Source installation requires Rust 1.95 or newer. Development and release builds use Rust 1.99.
Run kache init after upgrading to refresh compiler shims. Use documented JSON output for scripts; human output may change.
Documented CLI commands, options, configuration keys, and public Rust APIs follow major-version compatibility. JSON fields may be added; consumers should ignore unknown fields. Removing fields or changing their meaning requires a new schema version and a major release.
Cache-key recipes and private storage layouts can change during 1.x, so an upgrade may cause misses and rebuilds. The planner service and Helm chart remain previews. Compatibility policy. #1435 by @jleni.
kache clean uses tracked targets and sibling worktrees. Pass a path to inspect an untracked directory.

Docs

The README now starts with installation and a cache-reuse demo. The guides separate first-time setup from remote configuration, troubleshooting, and compiler-specific limits. #1438, #1439 by @jleni.