hammerkit

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 hit

Causes

CauseMeaning
never cachedNo 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, … changedThe 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; fi

Showing 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 your with passed) or extended task.
  • A variable taken from your shell or a .env file is listed with from $NAME and whether it is set, never its value.

--json prints the same information as a list for tools. Services are not part of it yet.

  • hammerkit run --explain prints the miss cause inline for every task that rebuilds, and adds a cause column to the build summary.
  • hammerkit run --dry-run prints 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)

On this page