Caching

Caching

Beez caches work at three levels to skip redundant steps and per-file checks. All on-disk cache data lives under the configured cache root (default .cache/).

Contents

• Caching Overview - the three layers at a glance
• Step Cache - skip whole steps when inputs and outputs are unchanged
• Success Cache - skip individual files inside Lua callbacks
• Glob Metadata Cache - in-memory glob acceleration per run
• Artifact Patterns - input, output, mutate and output tracking
• Cache Keys and Invalidation - what goes into fingerprints and when cache goes stale
• Cache Storage and Maintenance - compression, write timing, cleanup
• Caching Troubleshooting - common problems and fixes

Quick reference

Layer	When it applies	Disable
Step cache	Step has input, output, or mutate	--no-cache
Success cache	Lua callback uses ctx.file_success_cached() etc.	--no-cache
Glob metadata	performance.cache_fs_metadata = true	config

beez build --no-cache           # disable all Beez caching
beez --clean-cache build        # delete cache, then build
beez --update                   # recompress cache files

Related pages

• Cache Settings - configuration keys
• Cache and Maintenance Flags - CLI flags
• Step Declaration - artifact fields on steps
• Step Context - success cache API