Caching

Every task should declare the source files it requires. Based on those files, hammerkit checks whether anything changed since the last run that requires the task's commands to run again. If all source files are unchanged, the task is skipped.

What gets cached, and what invalidates itCopy Anchor Link

The cached result is the task's generates output (plus the per-task state hammerkit keeps under .hammerkit). That is what gets reused — and what store / restore and remote backends move between machines.

A task's cache key has two parts:

• the task's definition: cmds, image (or the host OS for a local task), the CPU architecture, envs, mounts, shell, src and generates paths, the working directory, and the definitions of its dependencies, and
• its state: the declared src files (their content checksum by default, or their modification dates with modify-date) combined with the state of its dependencies, recursively.

So a task is re-run when its definition changes, when its src changes, or when anything it depends on changes — its dependencies' sources or their definitions. Use hammerkit explain to see which of these caused a rebuild.

Changing a task's description, labels or timeout does not invalidate it.

A task's src may point at what a dependency generates (an e2e task reading dist, say). Those files are not hashed again: they are represented by the dependency's definition and state. So the task has the same key on a clean checkout, where dist isn't built yet, as in a workspace where it is — which is what lets a clean CI checkout reuse what an agent pushed.

A cache hit restores the task's outputs where they are expected: a container task's exported directories and file outputs on the host, the rest in its volumes. Deleting an output (rm -rf dist) makes the task restore it from a cache backend, or run again.

All paths in the key are relative to the project root (the git root, or the directory of the main build file), so the same commit has the same keys in every checkout — on a laptop, a CI runner or an agent sandbox. That is what lets a remote cache be shared between machines.

Define source filesCopy Anchor Link

The following example declares package.json and package-lock.json as source files. Before each run, the checksums of those two files are compared with the checksums from the last successful run; if they are equal, the task is skipped.

tasks:
  install:
    src:
      - package.json
      - package-lock.json
    cmds:
      - npm install

Define source foldersCopy Anchor Link

The next example declares the src folder as the task source. To check whether the task can be skipped, the entire folder is traversed recursively.

tasks:
  build:
    src:
      - src
    cmds:
      - tsc -b

Define glob sourcesCopy Anchor Link

This example defines a glob pattern src/**/*.ts as the task source. This is similar to a folder source, but filters, for example, by file extension: every .ts file under src, in any subdirectory.

tasks:
  build:
    src:
      - src/**/*.ts
    cmds:
      - tsc -b

Globs are matched against paths relative to the task's directory, and may use environment variables ($DIR/**/*.ts). Several patterns are supported. Hammerkit matches globs with minimatch (the matcher behind node-glob); see its docs for all details. A quick summary:

• * Matches 0 or more characters in a single path portion.
• ? Matches 1 character.
• [...] Matches a range of characters, similar to a RegExp range. If the first character of the range is ! or ^ then it matches any character not in the range.
• !(pattern|pattern|pattern) Matches anything that does not match any of the patterns provided.
• ?(pattern|pattern|pattern) Matches zero or one occurrence of the patterns provided.
• +(pattern|pattern|pattern) Matches one or more occurrences of the patterns provided.
• *(a|b|c) Matches zero or more occurrences of the patterns provided.
• @(pattern|pat*|pat?erN) Matches exactly one of the patterns provided.
• ** If a "globstar" is alone in a path portion, then it matches zero or more directories and subdirectories searching for matches.
• {a,b} Matches either of the comma-separated alternatives.

checksum vs. modify-dateCopy Anchor Link

checksum is the default method, both locally and in CI. It compares the content of the src files, so a result built on one machine is correctly reused on another — including a fresh CI runner.

Selecting a cache methodCopy Anchor Link

By default a task is skipped based on the content checksum of its source files. The cache field can change the method per task. The shorthand form takes one of checksum, modify-date or none.

tasks:
  build:
    cache: modify-date
    src:
      - src
    cmds:
      - tsc -b

Changing the default for all tasksCopy Anchor Link

A task without a cache field uses the built-in default cache, and its method is the global default rather than something declared on the task. There are two ways to change that default for every such task.

Per run - the --cache flag. Pass --cache <method> to set the method for all tasks that did not declare their own cache. The choices are checksum, modify-date and none. The default is checksum both locally and in CI, so a result cached on one machine is reused on the other. See execute for the full option reference.

hammerkit build --cache checksum

Persistently - redeclare caches.default. To change the default cache backend for every task (for example to share results through a remote bucket), redeclare the built-in default cache in the build file. See caches.

Remote caches & backendsCopy Anchor Link

A task can reference a named cache with a remote backend, so its result can be shared between machines and CI runs. Reference a cache by name and optionally override its method.

caches:
  remote:
    method: checksum
    backend:
      type: s3
      bucket: my-build-cache
      region: eu-central-1

tasks:
  build:
    cache:
      name: remote        # use the "remote" cache declared above
      method: checksum    # optional, overrides the cache method
    src:
      - src
    generates:
      - dist
    cmds:
      - tsc -b

When the cache has a remote backend, hammerkit pulls the result before the task runs if it is missing locally, and pushes the result after a successful run. The built-in backends are local, s3 and registry; the s3 backend also covers any S3-compatible store such as MinIO, Cloudflare R2 and Google Cloud Storage, and the registry backend any OCI container registry (GHCR, Docker Hub, ECR, …). See caches for the full backend reference, the R2/GCS examples and the pull/push behavior.

To keep the network out of the build, leave tasks on the machine-local default cache and move entries explicitly with cache pull / cache push; see agents, workspaces and CI.

Limitations: what the cache can't seeCopy Anchor Link

Hammerkit assumes a task is a function of its declared inputs: the same definition, the same src contents and the same dependencies produce the same outputs. A cache hit replays the outputs of the first run with those inputs. When a task's result depends on anything else, the cache can serve a stale result — so these are the places to look when you set up a build.

Inputs hammerkit doesn't trackCopy Anchor Link

Results hammerkit doesn't checkCopy Anchor Link

• Outputs are checked for existence, not content. Deleting an output (rm -rf dist) makes the task restore or rebuild it, but editing a file inside dist by hand is not noticed. Run hammerkit clean after manual changes.
• Dependency outputs are trusted. A task reading what a dependency generates is keyed by the dependency's definition and sources, not by those files. A dependency that breaks one of the rules above passes the problem on.
• Non-deterministic tasks. If the same inputs can produce different outputs (timestamps inside archives, test order, flaky tests), a cache hit freezes one of them. A flaky test that passed once stays "passed" until its inputs change.
• modify-date only sees timestamps. Content that changes while the modification time is preserved (cp -p, rsync -t, extracting an archive) is not noticed. Keep the default checksum for anything shared.
• Trust. A shared cache hit means "someone with write access ran this". Decide who may push — see who may write to the cache.

Changes that rebuild more than neededCopy Anchor Link

These never serve a stale result, but cost a rebuild:

• Env values are part of the key, including tokens: rotating NPM_TOKEN rebuilds every task that declares it. Declare credentials only on the tasks that use them.
• Build-file envs apply to every task in the file, so changing one rebuilds them all. Put a value on the tasks that use it when only those should rebuild.
• The CPU architecture is part of the key. An arm64 laptop and an x64 CI runner don't share entries.

Checking your buildCopy Anchor Link

• Run the build twice: the second run should report every task as cached. A task that rebuilds without a change reads something that differs between runs — hammerkit explain names it.
• Change one source file: only the tasks reading it, and the tasks depending on them, should rebuild (hammerkit run --dry-run shows the plan without running).
• Audit regularly, for example nightly: build once with the cache and once with --cache none on a clean checkout, and compare test results or output checksums. A difference points at an input a task doesn't declare.