Skip to main content
Version: Next

Key Concepts

This page connects the main Terrabuild concepts without repeating the full reference. Use it after the quick start when you want the mental model.

Core Model​

Workspace and Project​

A workspace is the monorepo root. It contains one WORKSPACE file with shared configuration such as target policies, variables, and extension defaults.

A project is a buildable unit inside that workspace. It contains one PROJECT file with project-specific configuration such as outputs, dependencies, labels, and commands.

workspace/
├── WORKSPACE          # Global configuration
├── project-a/
│   └── PROJECT        # Project-specific configuration
└── project-b/
    └── PROJECT

Target, Task, and Node​

  • Target: a named goal such as build, test, or dist.
  • Task: one concrete target execution for one project.
  • Node: that task represented inside the build graph.

Relationship: target defines intent, task is the runtime instance, node is the graph representation.

Extension, Action, and Command​

  • Extension: a capability provider such as @dotnet, @npm, or @docker.
  • Action: an operation exposed by an extension such as build, test, or publish.
  • Command: one use of an action inside a target, for example @dotnet build { }.

Build Graph​

Terrabuild expands selected targets into a DAG:

  • nodes are tasks
  • edges are dependencies between tasks
  • the graph determines order, parallelism, and rebuild propagation

See Graph for the detailed walkthrough.

Dependency Resolution​

Terrabuild uses target dependency syntax to describe execution order:

  • target.^build: run build for upstream dependency projects first
  • target.build: run build for the current project first

Target references only create dependencies when the referenced target exists in the relevant project scope. Circular target dependency chains are invalid and are reported before commands run.

target build {
  depends_on = [ target.^build ]
}

target dist {
  depends_on = [ target.build ]
}

Workspace target dependencies and project target dependencies are combined for the same target. See Workspace Target Block and Project Target Block for the reference form.

Change Detection and Cache Keys​

Terrabuild hashes project files, dependency state, commands, and evaluated inputs to decide whether a task can be restored or must be built. Because the hash is deterministic, the same work can be reused across machines and branches when inputs match.

A failed cached run is not restored as successful output. Terrabuild reports it as a summary unless you pass --retry, which makes the task build again.

See Caching and Tasks.

Batch Builds​

A cluster is a group of compatible tasks built together in one batch. This lets extensions such as .NET or pnpm reuse native tooling more efficiently.

See Batch for details.

Keep Reading​

  • Graph for how Terrabuild models work
  • Tasks for build-vs-restore decisions
  • Glossary for short term definitions
  • Syntax for the file format