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.
tasks:
install:
cmds:
- npm install
src:
- package.json
- package-lock.json
generates:
- node_modulesThe npm install uses an include: each project has its own package.json, but the task definition is the same.
tasks:
build:
deps: [npm:install]
cmds:
- node_modules/.bin/tsc -b
includes:
npm: ../../build.npm.yamlThe build task depends on the included install task, which ensures that node_modules is installed first.
tasks:
build:
deps: [npm:install, a:build]
cmds:
- node_modules/.bin/tsc -b
references:
a: ../a
includes:
npm: ../../build.npm.yamlThe 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.
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| Field | Meaning |
|---|---|
git | Repository URL or path. Required. |
ref | Branch, tag or commit SHA. The repository's HEAD when left out. |
path | Build file, or a directory holding one, inside the repository. The repository root when left out. |
with | Values 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:
envs:
NODE_VERSION: 22
tasks:
ci:
image: node:$NODE_VERSION-alpine
cmds:
- npm ci
src:
- package.json
- package-lock.json
generates:
- node_modulesincludes:
npm:
git: https://github.com/no0dles/hammerkit.git
ref: v1.16.0
path: catalog/npm
with:
NODE_VERSION: 22A 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.
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 in | Working directory | Use it when | |
|---|---|---|---|
| references | A whole other build file (its tasks + services) | The referenced file's own directory | The other file is its own project (a sub-package you also want to build in place). |
| includes | A whole other build file | The including file's directory | You want to reuse a task definition and run it here — the same install/build template across every package. |
| extend | A single task, as a base template | The current task's file | One 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.
References
References allow the usage of tasks defined in other build files. They can be used to split up tasks into separate files.
Caches
Caches describe how a task decides if it can be skipped and where its results are stored. With pluggable backends the cache can be shared across machines and CI runs.