Explain
Explain why a task is a cache hit or a cache miss — without running anything.
hammerkit explain [task] predicts, for every task in scope, whether the next run
would be a cache hit or a cache miss, and names the input that caused each
miss. Nothing is executed and no container is started. It uses the same state-key
engine as run, so the prediction matches what run will do.
hammerkit explain e2e• build: cache miss
cause: source changed: src/app.js
cause: dependency changed: install
• e2e: cache miss
cause: dependency changed: build
• install: cache hitCauses
| Cause | Meaning |
|---|---|
never cached | No result for this task has been recorded yet. |
source changed: <file> | A file in src was added, removed or changed. |
dependency changed: <task> | A task in deps (transitively) has a different state. |
command, image, env, mounts, … changed | The task definition itself changed (see cache identity). |
A task with cache: none is reported as uncacheable.
JSON output
--json prints a machine-readable list, for CI annotations or agents:
[
{
"taskId": "ea717e7627d2e12e24acd731af1d1b364c510f32",
"taskName": "build",
"status": "miss",
"causes": [
{ "kind": "source-changed", "identifier": "src/app.js" },
{ "kind": "dependency-changed", "identifier": "install" }
]
}
]Gating a CI step
--check turns the prediction into an exit code: 0 when no task in scope would
be a cache miss (uncacheable tasks do not count), 1 otherwise. After a
cache pull it tells a pipeline whether a run has anything to
do, so a job can skip expensive setup:
hammerkit cache pull --remote ci
if hammerkit explain test --check; then echo "up to date"; else hammerkit run test; fiShowing a task's definition
--definition prints, instead of the cache prediction, the task as hammerkit resolved it:
the image, commands, src, generates, deps and envs after includes, inputs and
extend were applied, and where each part came from. It is how you review what an
included or catalog task does before you
run it. Nothing is executed.
hammerkit explain --definition npm:install• npm:install
defined in: catalog/npm/build.yaml of https://github.com/no0dles/hammerkit.git at v1.16.0 (commit 7b183f08ebed)
included as: npm
description: install the locked dependencies with npm ci
image: node:22-alpine
src: package.json, package-lock.json
generates: node_modules
cmd: npm ci
env NODE_VERSION: 22 (input of include npm)- defined in names the file, and for a git include the repository, ref and the commit the cache holds, so you see exactly which version runs.
- Each env value shows where it was declared:
task,build file,input of include <name>(a value yourwithpassed) orextended task. - A variable taken from your shell or a
.envfile is listed withfrom $NAMEand whether it is set, never its value.
--json prints the same information as a list for tools. Services are not part of it yet.
Related
hammerkit run --explainprints the miss cause inline for every task that rebuilds, and adds a cause column to the build summary.hammerkit run --dry-runprints the execution plan in order — see execute.
Options
Usage: hammerkit explain [options] [task]
Options:
-f, --filter <labels...> filter task and services with labels
-e, --exclude <labels...> exclude task and services with labels
--env <name> environment
--cache <method> caching method to compare (choices: "checksum", "modify-date", "none", default: "checksum")
--json emit the explanation as JSON (default: false)
--check exit with code 1 when any task would be a cache miss (default: false)
--definition show the resolved definition of the tasks and where it came from instead (default: false)