> For the complete documentation index, see [llms.txt](https://no0dles.gitbook.io/hammerkit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://no0dles.gitbook.io/hammerkit/task.md).

# Task

Tasks are pieces of work that you need to build or develop your project.

The minimal task just contains a list of commands.

```yaml
tasks:
  example:
    cmds:
      - echo "minimal example"
```

{% hint style="info" %}
**Local vs. container — the one rule to remember.** If a task declares an `image`, its commands run **inside that container**. If it has no `image`, they run **directly on your host** using the tools installed there. Everything else (sources, outputs, caching, dependencies) works the same in both cases. Containers are the recommended default: they remove the need to install build tools on every machine and make a build behave identically on your laptop and in CI. See [run a task in a container](/hammerkit/task/container.md).
{% endhint %}

## Anatomy of a task

A task is built from a small, fixed set of fields:

| Field       | Purpose                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `cmds`      | The commands to run, in order.                                                                                   |
| `image`     | Run the commands inside this container image. Omit to run on the host.                                           |
| `src`       | Input files/folders. Used for [caching](/hammerkit/task/caching.md) — unchanged sources let the task be skipped. |
| `generates` | Output files/folders the task produces. These are what gets cached, stored and restored.                         |
| `deps`      | Other tasks that must run first (see [dependencies](/hammerkit/task/dependencies.md)).                           |
| `needs`     | Services that must be running first (see [needs](/hammerkit/task/needs.md)).                                     |
| `mounts`    | Extra paths to make available to a container task (see [container](/hammerkit/task/container.md)).               |
| `envs`      | [Environment variables](/hammerkit/build-file/environment-variables.md) for the commands.                        |
| `labels`    | Group/filter tasks (see [labels](/hammerkit/labels.md)).                                                         |
| `cache`     | The [caching](/hammerkit/task/caching.md) method/backend for this task.                                          |

## Source files (`src`)

Tasks that depend on input files should declare them under `src`. Hammerkit detects if the `src` files have changed compared to previous runs and skips execution if they are unchanged.

```yaml
tasks:
  build:
    description: "run typescript build"
    src:
      - tsconfig.json
      - src
    cmds:
      - tsc
```

## Generated files (`generates`)

Tasks that produce output files should declare them under `generates`. Hammerkit can store generated files into archives, which can be used to save and restore build outputs.

```yaml
tasks:
  build:
    description: "run typescript build"
    src:
      - tsconfig.json
      - src
    generates:
      - dist
    cmds:
      - tsc
```

### Exporting generated files

By default generated files of a container task stay inside the container volume. Mark a generate with `export: true` to copy it back into your workspace after the task ran. This is useful when another tool outside hammerkit needs the produced files, for example a build artifact you want to inspect or publish.

```yaml
tasks:
  build:
    image: node:alpine
    generates:
      - path: dist
        export: true
    cmds:
      - tsc -b
```

### Resetting generated files on change

By default a generated directory keeps its contents between runs, so a re-run can reuse previous output. Mark a generate with `resetOnChange: true` to wipe it before the task runs again, guaranteeing the task starts from an empty output directory and no stale files from a previous run remain.

```yaml
tasks:
  bundle:
    image: node:alpine
    generates:
      - path: dist
        resetOnChange: true
    cmds:
      - node bundle.js
```


---

# 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/task.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.