File index tracking
You run the generator on every build, and it shares a folder with code people wrote by hand. It must replace what it owns, remove what no longer exists, and never touch anything else. It does that by marking every file it writes.
Ownership headers
Section titled “Ownership headers”Every generated file (and, with separate output, generated barrel) starts with a header naming its source, generation time, and a content hash:
// @generated by Cratis. Source: Tasks.Registration.RegisterTask. Time: 2026-09-24T20:35:55.3970000Z. Hash: FDB6670D1623B9F818509BA14942A78DF19A6EDEA92F42D7DD2D75CDB7D04895Never edit a file with this header; the next run replaces it.
What a run changes
Section titled “What a run changes”| File | Behavior |
|---|---|
| An owned file whose content did not change | Kept byte for byte, with its timestamp |
| An owned file whose content changed | Replaced |
| An owned file for an artifact that no longer exists | Removed, unless --skip-output-deletion |
| A hand-written file | Never overwritten or deleted |
A hand-written index.ts barrel in separate output | Never replaced; when stale owned files are deleted, only its exports of those files are removed. Directory and package re-exports stay |
A hand-written index.ts in the artifacts tree | Untouched in co-located mode; no barrels are written there |
Co-located output skips barrels automatically. With separate output, --skip-index-generation stops the generator from writing them.
Output folder safety
Section titled “Output folder safety”The output root must exist. The generator resolves symbolic links in its ancestors, such as /tmp on macOS, to their real path, and refuses symbolic links inside the output.
Related
Section titled “Related”- Configuration
- Low-level manifest, which writes files with different rules