Project version export and import
A project version can be exported as a whole — to a ZIP file with a Git folder structure or directly to a Git repository (GitHub, GitLab, and other Git servers) — and imported back into the same or another project. Both operations are opened from the dropdown menu next to the version switcher in the interface header.
The mechanism serves two purposes:
- backing a version up to a file
- keeping the project configuration in a version control system, where the differences between exports appear as an ordinary diff, and versions exported to different branches can be merged in Git and imported back
Git connections (repository URL, authentication) are configured separately in the connections section; the export and import dialogs only let you pick one of the already saved connections.
Access to the functions
- Export is available to any user with access to the project, including viewers: export is a read operation
- Import is available to the Super administrator, Administrator, and Developer roles (as well as users with the project access level "Developer" or "Project manager"). For analysts and viewers the "Import from Git" menu item is disabled
All export and import operations, including failed ones, are recorded in the system journal.
Opening the dialogs
Open the dropdown menu next to the version switcher in the interface header:
| Menu item | Dialog opened | Availability |
|---|---|---|
| Export to Git | "Export project version" | A project and a version are selected |
| Import from Git | "Import project version" | A project and a version are selected, and your role permits import |
Both dialogs support transfer via a file as well as directly via Git — the method is chosen in the "Export mode" field (for export) or the "Source" field (for import).
What is transferred
An export is always complete: selecting individual objects is not supported. The only option is including the RMD change history.
| Data | What is transferred |
|---|---|
| RMD data | Measures, dimensions, facts with the values of all fields, column settings, and value lists |
| Dimension groups | Dimension groups with their dimensions and levels |
| Fact tables | Table parameters, attributes and their settings, architector joins, positions, dimension group links, fact-table-level verification filters |
| Data marts | Data mart parameters, element composition, hidden elements, filters, aggregations, positions, joins |
| Connections | Connection parameters and the password in encrypted form (see "Connections and passwords" below) |
| Verification filters | Version-level filters |
| Data model | Positions of elements on the data model canvas |
| RMD change history | Only when the "Include RMD change history" checkbox is set; up to 50,000 records, with a warning when the cap is exceeded |
Not transferred: physical data mart views and actual data from connected databases, the cached connection schema (refreshed after import), plaintext passwords and API keys, cell discussions, system journal entries, IP whitelist/blacklist settings, license information, and project-level data (data types, project members, the global version reference).
Export file format
An export is a directory tree of JSON files packed into a .dfexport.zip archive. The tree layout is the same for export to a file and to Git: manifest.json with the export metadata, project.json and version.json, the rmd/ directory with measures, dimensions, facts, and dimension groups as separate files, one directory per fact table under fact_tables/, per data mart under data_marts/, and per connection under connections/, plus an auto-generated README.md and a .gitattributes file.
The format is deterministic: re-exporting an unchanged configuration produces byte-identical files, so Git shows real changes only, and exports of different versions of the same project land on the same paths and can be compared with each other.
Exporting to a file
In the "Export project version" dialog fill in the following fields:
| Field | Required | Description |
|---|---|---|
| Project name | — | The current project, read-only |
| Project version | Yes | Version selector; the current version is pre-filled. The global version is marked with an icon, deleted versions cannot be selected |
| Include RMD change history | No | Checkbox, cleared by default |
| Export mode | Yes | "ZIP file with Git folder structure" (default) or "Direct export to Git" |
In the "ZIP file with Git folder structure" mode, the system packs the version into an archive and the browser immediately downloads the file named <project>_<version>_<YYYYMMDD_HHMMSS>.dfexport.zip. After a successful export, the notification "Project version exported" is shown.
The export size is limited to 100 MB. Produced archives remain downloadable for 7 days and are then deleted automatically.
Exporting directly to Git
When the "Direct export to Git" mode is selected, two more fields appear in the dialog:
| Field | Description |
|---|---|
| Git connection | One of the saved Git connections available to you |
| Branch | Selecting a connection pre-fills its default branch, after which the list is extended with all repository branches |
The "Export" button stays disabled until a version and a connection are selected. The system then:
- Prepares the repository: an empty repository is initialized, an existing branch is cloned, and a missing branch is created from the default branch (so branches share a common ancestor and can be merged with Git itself)
- Replaces the project tree in the repository in full, including deletion of files of elements that were deleted in DataForge
- Checks for changes: if nothing has changed, no commit is created and the notification "No changes: the repository already contains this configuration" is shown
- Creates a commit on your behalf (the name and email of your account) with a message of the form
Export: <project> / <version>and pushes it. The notification "Exported to branch """ is shown
The size of an export to Git is limited to 200 MB. If the RMD change history is included, a warning is shown: the history grows with every export and inflates the repository, so it is recommended to include it only in file backups.
Importing a version
An import is always performed into the current project. In the "Import project version" dialog fill in the following fields:
| Field | Required | Description |
|---|---|---|
| Project name | — | The current project, read-only |
| Target project version | Yes | "Create new" or "Replace existing" |
| New version name | For the "Create new" mode | Maximum 64 characters; the first character must be a letter or digit; letters, digits, _, ., -, and spaces are allowed. The name must be unique among the project's versions |
| Select version | For the "Replace existing" mode | List of active versions; the global version is marked with an icon |
| Source | Yes | "ZIP file with Git folder structure" (default) or "Direct import from Git" |
| Include RMD change history | No | Apply the RMD change history if the source contains it |
| Load file for import | For the file source | Selection of a .zip file; a file larger than 100 MB is rejected with the message "The file exceeds the maximum size of 100 MB" |
| Git connection, Branch | For the "Direct import from Git" source | The same fields as for export: a saved connection and a repository branch |
The "Import" button stays disabled until the target version and the source are set.
Validation
An import runs in two steps: first the source is parsed and validated, and only then is the validated data applied. Errors block the import; warnings do not.
- Errors: a corrupted archive or unparseable files, missing required files, an incomplete manifest, an export format newer than the system supports, invalid or duplicate element identifiers, and exceeding the volume limits (at most 10,000 RMD items, 500 fact tables, 1,000 data marts; 100 MB for an archive, 200 MB for a tree from Git, at most 20,000 files)
- Warnings: an export made by an older product version (some features may be missing), references to non-existent elements, duplicate element names, circular formula dependencies (the cycle surfaces in the RMD exactly as it does for hand-entered data), unrecognized files (ignored), and incomplete merge information
If validation finished with errors, the import does not start and you see a notification with the list of messages. A validated archive is kept for one day; applying the import later fails with the message "The uploaded archive has expired, validate the file again".
Import modes
- Create a new version. A new version with the given name is created in the project, and its content is taken from the source. Creating a version by import is subject to the license limit on the number of versions. After a successful import, the notification "Import finished successfully. Version "
" is ready" is shown - Replace an existing version. The operation is irreversible, so the "Replace existing version" confirmation dialog opens first, with a warning and a summary: the project name, the version being replaced, and the import source (the file name or the connection and branch). Cancelling the confirmation preserves the filled-in import form. On confirmation, the entire content of the target version is replaced with the content of the source; the version keeps its name and its place in the version list
If the replaced version is the one currently open, the interface reloads it automatically — the same way as when switching versions. From the pages of a specific fact table or data mart, you are redirected to the corresponding list
In both modes, and whether the source is a file or a Git repository, every fact table and data mart created by the import belongs to the user who runs the import, as if they had created it by hand. The owner recorded in the export is not used, so the Owner of imported elements is always filled in, even when the original author does not exist in the target system.
Importing from Git and merged branches
When importing from Git, the system clones the specified branch through the selected connection and locates the exported project in the repository: the repository path set on the Git connection is used first, otherwise the single directory containing an export; among several, the one belonging to the current project is chosen. If the export cannot be located, a message asks you to check the repository path of the Git connection.
Merged branches. If the branch contains a merge commit, the system detects it, identifies which exported versions were merged (branch, export date and author for each), and records this provenance on the created or replaced version. From then on it appears in the manifest of every new export of that version. If the merge information is incomplete, a warning is issued; this does not block the import.
This enables a collaborative workflow:
- User A and user B export their versions to different branches of the same repository
- The branches are merged in Git; conflicts are resolved with the usual Git tools (an element added in only one branch merges automatically)
- The merged branch is imported back into DataForge as the final merged version
A version imported from Git keeps a reference to the connection it was loaded through. The reference always reflects the latest import: importing from Git again repoints it, importing from a file clears it, and deleting the Git connection only clears the reference without affecting the version.
Connections and passwords
Connection parameters are transferred together with the version. The password is exported only in encrypted form — the plaintext password never appears in the export files.
| Situation on import | Result |
|---|---|
| The password is decrypted successfully (import into an instance with the same system key) | The password is restored and the connection is active |
| The password could not be decrypted (a different instance) or is missing | The password is empty and the connection is marked with an error — re-enter the password and verify the connection |
| The connection was disabled in the source | The connection stays disabled |
The cached schema structure is not transferred, so after an import refresh it from the connections section.