File Formats on Divekit

config.json

Mon, 01 Jan 0001 00:00:00 +0000

config.json is the primary distribution configuration file used by divekit distribute, fetch, patch, overview, and related commands.

Default location:

.divekit/distributions/<distribution>/config.json

Current Stored Format

The current persisted format is a flat version: "2.0" document. Internally, Divekit still expands this into named targets such as work and eval.

{
 "version": "2.0",
 "remote": "gitnrw",
 "groupId": 12345,
 "members": {
 "path": "$DIVEKIT_MEMBERS/st2_members.json",
 "permissions": "developer"
 },
 "evaluationPipeline": {
 "enabled": true,
 "groupId": 67890
 },
 "snapshot": {
 "remote": "research",
 "groupId": 24680
 }
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"2.0"`.
`remote`	string	Host alias from `~/.divekit/hosts.json`.
`groupId`	integer	Work target group ID.
`name`	string	Optional repository name template. When omitted, Divekit uses `{{distribution}}-{{uuid}}`.
`members`	object	Member source and default permissions.
`members.path`	string	Path to the `members.json` file. Supports `$DIVEKIT_MEMBERS/...` and relative paths resolved through the members base directory.
`members.permissions`	string	GitLab access level assigned to configured members, for example `guest`, `reporter`, `developer`, `maintainer`, or `owner`.
`evaluationPipeline`	object	Enables separated eval target handling.
`evaluationPipeline.enabled`	boolean	Enables the generated `eval` target and cross-repository setup.
`evaluationPipeline.groupId`	integer	Optional group ID for eval repositories.
`groupLayout`	object	Controls how student and eval groups are derived.
`groupLayout.mode`	string	Group-resolution strategy: `distribution-subgroups` (default) or `legacy`.
`groupLayout.rootGroupId`	integer	Optional root group ID used to derive distribution subgroups. Defaults to the work target’s `groupId`.
`snapshot`	object	Optional research snapshot target configuration.
`snapshot.remote`	string	Host alias from `~/.divekit/hosts.json` used for snapshot writes. Defaults to the work target remote.
`snapshot.groupId`	integer	Snapshot root group used by `divekit snapshot`. Interactive runs can store this after you choose a root group.
`deleteExistingRepositories`	boolean	Destructive reset option before distribution.
`scripting`	object	Language and file-extension mapping used by scripting and token tooling.
`scripting.languages`	array of strings	Enabled language packs. If omitted in auto mode, Divekit can discover languages.
`scripting.extensions`	object	Maps file patterns such as `*.java` to language packs.
`scripting.files`	object	File-specific mapping alias that is merged with `scripting.extensions`.
`scripting.mode`	string	Scripting mode. `auto` enables language discovery; object form may also use manual mappings.
`variables`	object	Global token delimiter and fixed values.
`variables.variableDelimiter`	string	Opening delimiter for tokens.
`variables.variableDelimiterEnd`	string	Optional closing delimiter when start and end should differ.
`variables.values`	object	Fixed token values available during distribution.

Repository Name Templates

The optional top-level name value is rendered once for each repository group. When omitted, Divekit uses {{distribution}}-{{uuid}}.

members.json

Mon, 01 Jan 0001 00:00:00 +0000

members.json defines which UUIDs are distributed and which users receive access to each repository.

The file location is configured via config.json -> members.path.

The canonical member value is the GitLab username. Optional display-name metadata can preserve course-internal or local names without changing the username used for GitLab operations. Each entry in groups represents one distributed repository group.

Format

{
 "version": "2.0",
 "displayNames": {
 "myname_extern": "myname"
 },
 "groups": [
 {
 "uuid": "team-01",
 "label": "Team 01",
 "metadata": {
 "fruit": "banana"
 },
 "members": ["alice", "myname_extern"]
 },
 {
 "uuid": "team-02",
 "label": "Team 02",
 "members": ["charlie"],
 "unassignedMembers": ["dana"]
 }
 ]
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"2.0"`.
`displayNames`	object	Optional map from GitLab username to local display name.
`groups`	array	One entry per distributed repository.
`groups[].uuid`	string	Stable identifier used in naming and state files.
`groups[].members`	array of strings	GitLab usernames that should receive access to that repository.
`groups[].unassignedMembers`	array of strings	Optional members that were known locally but could not be assigned.
`groups[].label`	string	Optional human-readable group label. Used by repository name templates such as `{{label}}` and `{{slug}}`.
`groups[].metadata`	object	Optional group-level string metadata. Used by repository name templates such as `{{metadata "fruit"}}` or `{{.Metadata.fruit}}`.

Import Input

Interactive input, text files, and stdin use one repository group per non-empty row. A row with one value creates a one-person group:

variation.json

Mon, 01 Jan 0001 00:00:00 +0000

variation.json defines which content options Divekit may choose from during individualization.

This file is optional, but required if you want per-UUID variation selection.

Format

{
 "objects": [
 {
 "ids": "Vehicle",
 "objectVariations": [
 {
 "id": "car",
 "type": "class",
 "name": "Car",
 "variables": {
 "Vehicle": "Car"
 }
 },
 {
 "id": "truck",
 "type": "class",
 "name": "Truck",
 "variables": {
 "Vehicle": "Truck"
 }
 }
 ]
 }
 ],
 "relations": [
 {
 "id": "ownership",
 "type": "association",
 "source": "Vehicle",
 "target": "Owner",
 "options": ["one-to-one", "one-to-many"],
 "variables": {}
 }
 ],
 "logic": [
 {
 "id": "algorithm",
 "type": "implementation",
 "location": "src/logic",
 "options": ["simple", "complex"],
 "variables": {}
 }
 ]
}

Top-Level Sections

Key	Type	Notes
`objects`	array	Object-level choices keyed by `ids`.
`relations`	array	Relation-level choices keyed by `id`.
`logic`	array	Logic-level choices keyed by `id`.

Variation Fields and Token Overrides

Each object variation can contain more than just id, type, name, and variables.

individualization.json

Mon, 01 Jan 0001 00:00:00 +0000

individualization.json controls advanced processing behavior for variable replacement, solution deletion, warnings, file handling, artifact processors, and compatibility variation settings.

This file is optional. If it is missing, Divekit falls back to built-in defaults.

Minimal Example

{
 "variables": {
 "variableDelimiter": "$"
 }
}

Common Example

{
 "variables": {
 "variableDelimiter": "$",
 "values": {
 "semester": "SS2026"
 }
 },
 "solutionDeletion": {
 "enabled": true,
 "files": ["src/main/java/Solution.java"]
 },
 "warnings": {
 "enabled": true,
 "ignore": ["*.tmp"],
 "variationResidues": {
 "typeWhiteList": ["java", "md"],
 "ignoreList": ["UUID"],
 "matchMode": "word",
 "ignoreRules": [
 {
 "paths": ["src/test/java/**"],
 "values": ["Dish"]
 },
 {
 "values": ["Dish|Meal"],
 "matchMode": "regex"
 }
 ]
 }
 },
 "processors": {
 "uml": {
 "mode": "both",
 "imageFormat": "jpg"
 },
 "tableHash": {
 "solutionTableFileName": "${id}.solution.md",
 "hashedSolutionTableFileName": "${id}.hashed.md",
 "tableConfigFileName": "${id}.config.json"
 }
 }
}

Top-Level Keys

Key	Type	Notes
`variables`	object	Token delimiters and fixed values.
`solutionDeletion`	object	Files, directories, and markers used to remove solution content.
`warnings`	object	Validation and unresolved-token warning behavior.
`fileManipulation`	object	Target-specific file naming conventions such as `_workrepo`.
`processors`	object	Built-in artifact processors such as UML source/image generation.
`relations`	object	Object-relation metadata.
`variableExtensions`	object	Prefix, suffix, and transformation maps.
`variations`	object	Unified compatibility container for variation data.
`objectVariations`	array	Legacy flattened object variations.
`relationVariations`	array	Legacy flattened relation variations.
`logicVariations`	array	Legacy flattened logic variations.

`variables`

This section controls token delimiters and fixed token values.

Plugin Configuration JSON

Mon, 01 Jan 0001 00:00:00 +0000

Plugin configuration files are owned by individual Evaluation Pipeline plugins. Divekit writes them when a plugin declares a configuration wizard and a user runs divekit plugin configure <suite> for all plugins of a suite or divekit plugin configure <suite>/<plugin> for one of them.

The exact keys belong to the plugin. Divekit only controls where the file is stored, how wizard fields are converted to JSON, and optional result metadata such as schemaVersion.

State Files

Mon, 01 Jan 0001 00:00:00 +0000

Divekit writes distribution state into the distribution directory. These files are generated and updated by commands such as distribute, fetch, patch, overview, and passcheck.

Default location:

.divekit/distributions/<distribution>/

individuals.json

individuals.json stores the concrete per-UUID variation selection that was actually used during distribution.

{
 "version": "2.0",
 "individuals": [
 {
 "uuid": "team-01",
 "selection": {
 "objects": {
 "Vehicle": "car"
 },
 "relations": {
 "ownership": "one-to-many"
 },
 "logic": {
 "algorithm": "simple"
 }
 }
 }
 ]
}

Use this file to inspect what was assigned. Do not treat it as the source of possible options; that belongs in variation.json.

materialization.json

Mon, 01 Jan 0001 00:00:00 +0000

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.

hosts.json

Mon, 01 Jan 0001 00:00:00 +0000

hosts.json stores named remote host entries used by remote fields in distribution config.

Default location:

~/.divekit/hosts.json

Recommended management command:

divekit auth

Format

{
 "version": "1.0",
 "hosts": {
 "gitnrw": {
 "host": "https://gitlab.git.nrw/",
 "tokenAt": "DIVEKIT_API_TOKEN",
 "maxWorkers": 8,
 "rateLimitDelayMs": 250,
 "enableConcurrency": true
 }
 }
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"1.0"`.
`hosts`	object	Map of host alias to host definition.
`hosts.<alias>.host`	string	Base URL of the GitLab or Git provider instance.
`hosts.<alias>.tokenAt`	string	Key name used to resolve the stored token.
`hosts.<alias>.maxWorkers`	integer	Optional per-host concurrency limit.
`hosts.<alias>.rateLimitDelayMs`	integer	Optional delay between requests in milliseconds.
`hosts.<alias>.enableConcurrency`	boolean	Optional concurrency toggle for that host.

Security Notes

hosts.json stores metadata and token references, not raw token values.
Divekit prefers the OS credential manager for actual token storage and falls back only when no keychain/keyring integration is available.
divekit auth unset <host> removes the configured host and deletes the stored token entry.