References

Each build file can have a references map pointing at other build files. The referenced file brings in more tasks and services, which you can then use directly from the cli or as task dependencies.

references:
  foo: project/foo

tasks:
  example:
    cmds:
      - echo "foo bar"

Naming and prefixesCopy Anchor Link

A referenced task is addressed as <prefix>:<taskName>, where the prefix is the key you gave it in the references map. The example task above becomes foo:example:

hammerkit foo:example

The same prefix:name syntax is what you use in deps and needs:

references:
  foo: project/foo

tasks:
  build:
    deps: [foo:example]
    cmds:
      - echo "after foo"

References can be nested — a referenced file can have its own references — and the prefixes stack (foo:bar:task). This same prefix rule is shared with includes and extend.

References keep their own working directoryCopy Anchor Link

The key difference from includes: a referenced task runs with its own directory as the working directory. Commands and relative src/generates paths resolve against the referenced file's location, not yours. Use a reference when the other file is a real project in its own right; use an include when you want to reuse a task definition in the current project's directory.