Caching Overview

Caching Overview

Beez has three separate caching mechanisms. They solve different problems and do not replace each other.

                    beez build
                        |
        +---------------+---------------+
        |               |               |
   Step cache     Success cache    Glob metadata
   (whole step)   (per file/key)   (per run, RAM)
        |               |               |
   .cache/          .cache/success/   in-process
   entries/         entries/
   index/           misses/

Step cache

Skips an entire step when nothing relevant changed and declared outputs still exist.

• Applies to steps with at least one of input, output, or mutate
• Works for shell steps and Lua callbacks
• Stores manifests under .cache/entries/ and fast indexes under .cache/index/

Example: a compile step with input = { "src/**/*.cpp" } and output = { "build/app" } runs only when sources change or the binary is missing.

See Step Cache.

Success cache

Skips individual units of work inside a Lua callback, typically one source file per lint or format run.

• Opt-in via ctx.file_success_cached() / ctx.cache_file_success() in step callbacks
• Stored under .cache/success/
• Tracks previous failures in .cache/success/misses/ for incremental re-check

Example: lint 500 files, change one, only that file is checked again.

See Success Cache.

Glob metadata cache

Speeds up repeated glob expansion within a single Beez invocation.

• In-memory only (not persisted)
• Enabled by performance.cache_fs_metadata (default true)
• Shared by step cache, success cache, and ctx.glob()

See Glob Metadata Cache.

What Beez does not cache

Not cached by Beez	Notes
Steps without artifact patterns	No input / output / mutate
Tasks and workflows themselves	Caching is per step
Compiler caches (ccache, sccache)	Separate toolchain feature
Arbitrary shell side effects	Only declared artifacts are tracked

Disabling cache

Method	Effect
beez --no-cache	Disables step and success cache for one run
cache.enabled = false in config	Disables both persistently
--dry-run	Skips cache lookups; does not execute steps

Directory layout

Default root: .cache/ (configurable via cache.path).

Path	Purpose
.cache/entries/	Step cache manifests (keyed by content hash)
.cache/index/	Per-step index files for fast lookup
.cache/success/entries/	Success cache manifests
.cache/success/misses/	Per-step failure lists
.cache/beez-compress.meta	Compression settings metadata
.cache/logs/	Run logs (not cache data, but colocated)

Safe to delete the whole .cache/ directory. Beez rebuilds cache entries on the next run.

Choosing a strategy

Goal	Approach
Skip rebuild when sources unchanged	Step cache with input + output
Incremental lint/format/analyze	Success cache in Lua callback
Faster glob in large repos	Keep cache_fs_metadata enabled
Force full run	--no-cache or --clean-cache

Next steps

• Artifact Patterns - declare what steps touch
• Cache Keys and Invalidation - when entries go stale
• DSL Patterns - incremental per-file example