# 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](/hammerkit/cli.md) or as [task dependencies](/hammerkit/task/dependencies.md).

{% code title=".hammerkit.yaml" %}

```yaml
references:
  foo: project/foo
```

{% endcode %}

{% code title="project/foo/.hammerkit.yaml" %}

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

{% endcode %}

## Naming and prefixes

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`:

{% tabs %}
{% tab title="shell" %}

```bash
hammerkit foo:example
```

{% endtab %}
{% endtabs %}

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

{% code title=".hammerkit.yaml" %}

```yaml
references:
  foo: project/foo

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

{% endcode %}

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](/hammerkit/build-file/includes.md) and [extend](/hammerkit/task/extending.md).

## References keep their own working directory

The key difference from [includes](/hammerkit/build-file/includes.md): 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.

{% hint style="warning" %}
Build-file `envs` do **not** cross a reference. Variables declared at the top level of one file are not visible to a referenced (or [included](/hammerkit/build-file/includes.md)) file — each file's `envs` are scoped to that file. Declare the variables a referenced task needs in that file (or on the task itself).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://no0dles.gitbook.io/hammerkit/build-file/references.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.