Artifact Patterns

Artifact Patterns

Step cache uses input, output, and mutate glob patterns to know what a step reads and writes.

step({
    name = "compile",
    phase = "build",
    scope = "default",
    input = { "src/**/*.cpp", "CMakeLists.txt" },
    output = { "build/app" },
    mutate = { "build/**/*.o" },
    run = "...",
})

Fields

Field	Meaning	Used for
input	Files read	Content hash in cache key; input stamps in index
output	Files created or replaced	Output existence check; output list after run
mutate	Files changed in place	Treated as inputs for hashing; also ordering conflicts

All fields are optional tables of strings (glob patterns). Omit a field with {} or leave it unset.

Glob syntax

Patterns are relative to the project root. Beez uses its built-in glob matcher (supports **, *, ?).

Examples:

"src/**/*.cpp"
"include/**/*.hpp"
"build/app"
"CMakeLists.txt"

Cacheability

A step is step-cacheable if any of the three fields is non-empty.

Steps with only a shell run and no patterns never skip via step cache.

Input hashing

For cache keys and index stamps, Beez expands input and mutate patterns and fingerprints matched files:

• Cache key: content hash of each file
• Index fast path: path, size, modification time (no full re-hash on hot path)

If a matched path is not a regular file, it is skipped for stamps.

Output tracking after run

Declared	Recorded outputs
output non-empty	All paths matching output globs
mutate only	All paths matching mutate globs
No output or mutate	Files changed under watched directories (default includes build/)

Implicit directory watch

When output and mutate are both empty, Beez snapshots files under directories inferred from output patterns, or build/ by default, and records files that changed (size or mtime).

Prefer explicit output or mutate for reliable caching.

Ordering and mutate

Steps in the same phase+scope with overlapping mutate patterns cannot run in parallel. Beez infers ordering to avoid concurrent writes to the same files.

Use explicit order() when overlap is not obvious. See Order Declaration.

Workers

ctx:spawn() accepts optional inputs and outputs arrays with the same glob string format. Workers with either field set can participate in worker-level step caching.

Examples

Compile (read sources, write binary):

input = { "src/**/*.cpp" },
output = { "build/myapp" },

Format in place:

mutate = { "src/**/*.cpp" },

Code generation:

input = { "schema/*.json" },
output = { "generated/**/*.h" },

No artifacts (always runs):

step({
    name = "deploy",
    phase = "deploy",
    scope = "default",
    run = "kubectl apply -f k8s/",
})

Next steps

• Step Cache - how patterns affect skip logic
• Cache Keys and Invalidation
• Step Declaration