Zig 0.13.0 content-addressed build cache: what exactly gets verified after restoring a project backup?

Short answer

Restoring only the project tree verifies nothing. Zig 0.13.0's content-addressed cache stores its reference hashes in the cache directory (by default the global one, e.g. ~/.cache/zig), not in the project. If that directory is absent, the build has nothing to compare against, so it treats every artifact as a cache miss and rebuilds silently. There is no "hash mismatch" diagnostic because a mismatch requires a stored hash to disagree with — and you didn't restore one.

What the cache actually does

The 0.13.0 release replaced timestamp-based incremental checks with content addressing: inputs to each build step (source bytes, compiler flags, dependency versions) are hashed, and outputs are stored under those hashes. The practical consequences for your scenario:

• Covered artifacts: compiler outputs such as object files and executables, plus the results of cached build steps. Test binaries are compiler outputs too, so they follow the same path. Fetched dependencies live in the cache's package store and are re-fetched and checked against their expected hashes if missing — that part of verification survives a project-only restore, because the expected hashes come from your lock/manifest, not from the cache.
• Not covered: the integrity of your restored source files themselves. Content addressing proves "this output corresponds to these inputs," not "these inputs are the same inputs I had before." If a restored source file was corrupted, Zig will happily build the corrupted source and produce a valid, correctly hashed artifact.

Getting a no-op build as restore confirmation

Yes — restoring the cache directory alongside the project is the way to get an "up to date" no-op build, and that no-op is the closest thing Zig offers to confirmation of a faithful restore. If any restored source file differs from what the cache recorded, the input hash changes and that step (and its dependents) rebuild. So the sequence is:

1. Back up the project tree and the cache directory. If you want the backup self-contained, point the cache into the project with zig build --cache-dir .zig-cache --global-cache-dir .zig-global-cache (or set this in your build environment) so both travel together.
2. After restoring, run zig build. A fast no-op means inputs match the recorded hashes. Any rebuild step identifies which inputs diverged.
3. For a stronger check, rebuild from scratch on the restored tree (rm -rf .zig-cache zig-out on a scratch copy, then zig build) and compare the resulting binary hashes against your original artifacts with sha256sum. Zig builds are largely reproducible for a fixed compiler version and flags, so identical outputs are good evidence — though this verifies reproducibility, not the cache mechanism itself.

Diagnostics: miss vs. mismatch

Zig 0.13.0 does not emit a user-facing distinction between "cache entry absent" and "cache entry present but stale" — both surface as the step simply running again. If you need visibility, zig build --verbose shows which steps execute; on a warm restored cache you should see almost none. One caveat worth flagging: this behavior is based on the documented 0.13.0 design, and cache internals have evolved in later releases, so verify against your exact zig version before relying on it in a backup policy.

Bottom line

The content-addressed cache is an incremental-build mechanism, not a backup-integrity tool. To use it as one: bundle the cache with the project, treat a no-op rebuild as your verification signal, and use external checksums of final artifacts if you need bit-identical proof independent of the build system.