hammerkit

Includes

Includes are similar to references, with one key difference: the working directory. An included build file runs in the directory of the file that includes it.

Includes are ideal for defining repetitive tasks once and reusing them in multiple places. Referenced files also split up tasks, but their working directory stays fixed to the directory they are in. For includes, the working directory is the directory of the including file.

The following example is a TypeScript monorepo with two projects, a and b. Project b depends on a, and both need up-to-date dependencies before compiling the source code.

build.npm.yaml
tasks:
  install:
    cmds:
     - npm install
    src:
      - package.json
      - package-lock.json
    generates:
      - node_modules

The npm install uses an include: each project has its own package.json, but the task definition is the same.

project/a/.hammerkit.yaml
tasks:
  build:
    deps: [npm:install]
    cmds:
      - node_modules/.bin/tsc -b

includes:
  npm: ../../build.npm.yaml

The build task depends on the included install task, which ensures that node_modules is installed first.

project/b/.hammerkit.yaml
tasks:
  build:
    deps: [npm:install, a:build]
    cmds:
      - node_modules/.bin/tsc -b

references:
  a: ../a
            
includes:
  npm: ../../build.npm.yaml

The build file of project b uses the same include for the npm install task. An additional reference to a and a task dependency on a:build ensure that project a is built before project b is compiled.

An include can also be an object with a path, which takes publish (and with):

includes:
  npm: { path: ../../build.npm.yaml }
  dev: { path: ./dev.yaml, publish: false }

publish: false keeps what the included file declares on your machine: a server leaves it out of the version it publishes. A git include takes publish too.

Include from a git repository

Instead of a path, an include (or a reference) can name a git repository. Use this to share build files between projects without copying them.

.hammerkit.yaml
includes:
  npm:
    git: https://github.com/no0dles/hammerkit.git
    ref: v1.16.0
    path: catalog/npm

tasks:
  build:
    deps: [npm:install]
    cmds:
      - npm run build
FieldMeaning
gitRepository URL or path. Required.
refBranch, tag or commit SHA. The repository's HEAD when left out.
pathBuild file, or a directory holding one, inside the repository. The repository root when left out.
withValues for the inputs of the included file, see inputs.

A plain string stays a local path, exactly as before. Prefer includes for shared task definitions: they run in your directory, while a git reference runs inside the cached checkout.

Inputs

An included file declares its inputs as ordinary top-level envs, each with a default, and uses them in its tasks. with replaces the defaults for one include:

build.npm.yaml (in the repository)
envs:
  NODE_VERSION: 22

tasks:
  ci:
    image: node:$NODE_VERSION-alpine
    cmds:
      - npm ci
    src:
      - package.json
      - package-lock.json
    generates:
      - node_modules
.hammerkit.yaml
includes:
  npm:
    git: https://github.com/no0dles/hammerkit.git
    ref: v1.16.0
    path: catalog/npm
    with:
      NODE_VERSION: 22

A name the included file does not declare is an error that lists the declared inputs, so a typo cannot silently do nothing. Values are strings or numbers. A value is used as it is written; to let CI set an input from outside, write NODE_VERSION: ${NODE_VERSION:-22}, which is the environment's (or a .env file's) NODE_VERSION, else 22. The same file included under two names with different inputs gives two independent sets of tasks.

Inputs of a local include

A local include (or reference) takes inputs too: write it as an object with a path.

.hammerkit.yaml
envs:
  NODE_VERSION: 24

includes:
  npm:
    path: build.npm.yaml
    with:
      NODE_VERSION: ${NODE_VERSION}
  web:
    path: web/build.yaml
    with:
      NODE_VERSION: ${NODE_VERSION}

${NAME} (or ${NAME:-default}) in a with value reads as it does in an envs value of the including file: the environment's (or a .env file's) NAME if it is set, else the including file's own envs value. So the Node version lives in one place, every include builds with it, and CI can still set it. A file that is included passes it on to its own includes the same way. A name the including file does not declare stays as it is, and the included file reads it from the environment as above. A value the including file builds from other variables (${BASE}-alpine) is passed on as it is written. A plain string path stays a local include without inputs, exactly as before.

Limits

Includes and references nest at most 32 levels deep, and one build file reads at most 1,000 files through them, 16 MiB of them, with at most 10,000 tasks and services; a file included again with other inputs counts again. The inputs one include passes on take at most 64 KiB. A file that includes itself with inputs that change each time stops at these with an error that names the include.

Caching and offline use

The first run fetches the repository at ref into ~/.hammerkit/includes and every later run uses that copy without touching the network, so a build keeps working offline and does not change underneath you. The cache is the pin: there is no lockfile.

  • A commit SHA (or a release tag you trust) gives the same content on every machine.
  • A branch is frozen at the commit of the first fetch on each machine, so a fresh CI runner can see newer content than a developer laptop. Pin a SHA when that matters.
  • A repository that was never fetched and is unreachable fails with an error naming the repository and ref. There is no silent fallback.

To update a branch or tag, run hammerkit includes pull; a commit SHA stays as it is. hammerkit clean --cache removes the cached repositories, so the next run fetches them again.

What a remote file may do

A remote build file contributes tasks, services, caches and environments. Fetching it runs nothing; commands run only when you run one of its tasks. Its own relative includes and references resolve inside the same repository at the same commit, and a path that leaves the repository is rejected. Private repositories use your usual git credentials (credential helpers, SSH keys); hammerkit never prompts and has no secrets of its own for this.

references vs. includes vs. extend — when to use which

All three reuse definitions, but they differ in what they reuse and where it runs:

What it pulls inWorking directoryUse it when
referencesA whole other build file (its tasks + services)The referenced file's own directoryThe other file is its own project (a sub-package you also want to build in place).
includesA whole other build fileThe including file's directoryYou want to reuse a task definition and run it here — the same install/build template across every package.
extendA single task, as a base templateThe current task's fileOne task is almost another, with a tweak or two.

A common monorepo setup combines them: an includes brings in a shared build.npm.yaml so each package runs install in its own directory, while references wire up cross-package build order. See the monorepo guide.

On this page