Cache Settings

Cache Settings

The cache section controls Beez's own step cache and success cache storage. This is separate from compiler caches like ccache.

cache = {
    path = ".cache",
    enabled = true,
    protect = false,
    hash = {
        algorithm = "fnv1a64",
        seed = 0,
    },
    compress = {
        algorithm = "none",
        level = 6,
        mode = "auto",
    },
}

path

Directory for cache data, relative to the project root unless absolute.

Default: .cache

Override when you want the cache on another disk or a CI cache mount.

enabled

When false, Beez does not read or write step cache or success cache.

CLI equivalent for one run:

beez --no-cache build

protect

When true, Beez applies file protection on cache writes (platform-dependent). Helps avoid partial reads of cache files during concurrent access.

Hash settings (cache.hash)

Used when fingerprinting file contents for cache keys.

algorithm

Value	Notes
fnv1a64	Default, fast 64-bit hash
fnv1a32	32-bit variant
crc32	CRC32
djb2	djb2 string hash
sdbm	sdbm hash

Changing the algorithm invalidates existing cache entries.

seed

Optional 32-bit seed mixed into hashes. Default 0.

Compression settings (cache.compress)

Cache manifest files can be stored compressed on disk.

algorithm

Value
none
gzip
zlib
rle
deflate
delta
vbyte

level

Compression level 0 to 9. Default 6.

mode

Value	Behavior
never	Store uncompressed
always	Always compress
auto	Compress when it saves space

Maintenance CLI flags

Flag	Purpose
--no-cache	Disable cache for one run
--clean-cache	Delete cache directory before run
--update	Recompress on-disk cache to match current compress settings

You can also clear cache from a task that removes .cache/ or runs beez --clean-cache.

Relationship to performance settings

performance.use_mmap_for_hashing and performance.mmap_hashing_min_bytes affect how file hashes are computed for cache keys, not where cache files are stored.

performance.cache_write_strategy controls when cache writes are flushed to disk.

What cache settings do not control

• Whether a step is cacheable (depends on input / output / mutate in the step definition)
• Per-file success cache API in Lua callbacks (see Caching when available)
• Compiler caching (ccache, sccache): that is outside Beez config

Next steps

• Caching - step cache, success cache, invalidation
• Performance Settings - threads and write strategy
• Environment Variables - env vars in cache fingerprints