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.
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.