materialization.json
materialization.json tells an Evaluation Pipeline run which files or directories from the work repository should be copied into the eval repository before tests and plugins run.
There are three related locations:
| Location | Kind | Purpose |
|---|---|---|
.divekit/eval-pipeline/materialization.json | Authoring config | Optional origin-side rules read during distribution or patching. |
.divekit/distributions/<distribution>/eval-pipeline/materialization.json | Authoring config | Optional distribution-specific rules. |
.divekit/materialization.json | Generated runtime manifest | Written into generated eval repositories and applied by the eval setup job. |
For most projects, prefer the path-marker form described below.
Use explicit JSON rules when the source and target paths should differ or when the source path should be optional.
If all rules come from path markers, no authoring materialization.json file is needed.
When both marker-derived and explicit JSON rules exist, Divekit merges them into one generated runtime manifest.
Project-level rules and distribution-specific rules are both included.
Duplicate rules are accepted only when they resolve to the same target, source, mode, and optional value.
Conflicting rules for the same target are rejected.
Format
Minimal useful authoring file:
{
"materialize": [
{
"source": "pom.xml",
"target": "pom.xml",
"mode": "overwrite"
}
]
}
Complete example:
{
"version": "1.0",
"materialize": [
{
"source": "src",
"target": "src",
"mode": "copy"
},
{
"source": "pom.xml",
"target": "pom.xml",
"mode": "overwrite"
},
{
"source": "optional-hints",
"target": "hints",
"mode": "copy",
"optional": true
}
]
}
Keys
| Key | Type | Notes |
|---|---|---|
version | string | Optional in authoring files. Generated manifests use "1.0". |
generatedBy | string | Written by Divekit in generated manifests. Do not write this in authoring files. |
materialize | array | List of materialization rules. |
source | string | Relative path in the fetched work repository. Required. |
target | string | Relative path in the eval repository. Required. |
mode | string | Either copy or overwrite. Required. |
optional | boolean | If true, a missing source path is ignored. Defaults to false. |
origin | string | Generated diagnostic metadata. Usually do not write this by hand. |
Paths must be relative repository paths. Absolute paths and paths that escape the repository root are rejected.
Modes
| Mode | Behavior |
|---|---|
copy | Copies the work-repo path to the eval repository. If both source and target are directories, their contents are merged. For files, the target must not already exist. |
overwrite | Removes the target path first, then copies the work-repo path into the eval repository. |
Legacy mode names tocopy and tooverwrite are accepted and normalized to copy and overwrite.
Prefer the canonical names in new authoring files.
Path Markers
Instead of writing JSON rules, mark files or directories in the origin repository with a materialization suffix:
src/main/resources/E2_copy_to_eval/
src/main/java/example/solution_overwrite_to_eval/
pom_overwrite_to_eval.xml
Divekit removes the suffix in generated work repositories and turns the marker into a generated runtime rule:
| Marker | Generated path | Generated mode |
|---|---|---|
<path>_copy_to_eval | <path> | copy |
<path>_overwrite_to_eval | <path> | overwrite |
The overwrite marker is _overwrite_to_eval.
_override_to_eval is not a recognized marker.
Markers can be used on a file or on one directory segment.
The marked source path is removed from generated eval repository content; only the generated .divekit/materialization.json manifest remains there.
In generated work repositories, Divekit strips the marker suffix from the path and from the contents of files below a marked path.
This keeps package names and similar path-derived identifiers aligned with the generated work-repo path.
Marker stripping also normalizes common separator leftovers:
| Authored segment | Generated segment |
|---|---|
solution_copy_to_eval | solution |
pom_overwrite_to_eval.xml | pom.xml |
E2_copy_to_eval | E2 |
If one path segment contains both materialization markers, Divekit rejects the path. If two rules resolve to the same target with different behavior, Divekit rejects the configuration.
Generated Manifest
The generated .divekit/materialization.json in an eval repository is runtime state.
It is applied by the eval setup job after the current work repository state has been fetched.
If there are no marker-derived or explicit rules, Divekit does not write a generated manifest.
Do not edit generated eval-repo manifests manually; change the origin-side marker paths or authoring config instead, then distribute or patch again.
Related pages: