Versioning and export

Saving a project to a git repository or exporting it as an archive: the exported tree, marked data files, and what syncing a project does not do yet.

In short

A project is saved like any other entity: a ZIP archive, or a git repository. The mechanism is common to every entity and covered in Git versioning; this page says what is specific to a project — what its export contains, and what it leaves behind.

Client Backend

What an exported project contains

The export produces a tree of readable files — JSON and Markdown — where each part of the project has its own file.

demo.linkr.interhop.org

sepsis-icu/

entity.jsonproject metadata

README.md

LICENSE.md

tasks.jsontasks and notes

organization.jsonthe workspace's organisation

.gitignore

cohorts

adults-sepsis.jsoncriteria

cohort-boardsthe cohort's patient board

concept-lists

vasopressors.json

dashboards

sepsis-follow-up.jsontabs + widgets

patient-dashboards

patient-sheet.json

databasesIDE connections

mimic-iv-demo.json

scripts

_tree.json

prepare_cohort.R

model.py

reference

icd10_codes.csv

datasets

_tree.jsoncolumns, types, labels

icu_stays

icu_stays.csv

icu_stays.edits.jsonedit journal

table-1.jsonan analysis

ventilation_collection

ventilation_collection.csv

ventilation_collection.edits.json

environmentsserver

python

pyproject.toml

uv.lock

renv.lock

attachments

.gitignore

**/*.csv
**/*.parquet
**/*.pq
**/*.xlsx
**/*.xls
**/*.edits.json
.cache/
!datasets/ventilation_collection/ventilation_collection.csv
!datasets/ventilation_collection/ventilation_collection.edits.json

Leaves with the exportExcluded by default (data)Marked for versioningserverServer modeClick a greyed file to mark it.

A project's export: entity.json and the readme at the root, one folder per kind of item — cohorts, cohort boards, concept lists, dashboards, patient boards, IDE connections (databases/), scripts, dataset structure and analyses, package environments (server mode), attachments. Data files are greyed: excluded by default. Click one to mark it, and watch the !path line it adds to the .gitignore.

Each cohort, concept list, dashboard or patient board has its own JSON file. IDE scripts leave as they are. A dataset leaves its structure in datasets/_tree.json — columns, types, labels, constraints — and its analyses in its folder, but not its rows. In server mode, environments/ joins them: the versioned list of Python and R packages; the installed packages themselves stay on the machine.

The format matters: because these files are text, a comparison tool shows exactly what changed between two versions of a cohort. An added criterion reads as one line.

Data does not leave by default

Every data file — CSV, Excel, Parquet — is excluded from export and versioning, wherever it sits: a dataset, or a reference file kept among the IDE scripts. The generated .gitignore ignores them all.

To include a specific file, mark it: right-click, Mark for versioning, in the datasets sidebar as in the IDE explorer. A !path line then re-includes it in the .gitignore. The decision is made file by file, never globally.

The reverse exists for code

A script leaves by default. To keep a code file on your machine — a draft, a script holding a local path —, right-click it in the IDE explorer, Remove from versioning: it drops out of the export and the repository.

What 'versioning a dataset' really carries

Marking a data file also includes its edit log — your cell corrections. That is consistent: for a hand-filled collection the log is part of the data. Both leave together, or neither does.

Saving and versioning

The Versioning & export page has two tabs.

demo.linkr.interhop.org

Versioning & export

Version control and export your project.

Export

Download your project as a ZIP archive with a git-friendly folder structure.

Data files are excluded by default for security. To include a specific dataset, mark it “for versioning” in the Datasets sidebar (right-click).

The two tabs of the Versioning & export page. Git repository comes first; Export downloads the complete tree as a ZIP. Click the tabs to switch between them.

Git repository — the default tab. It connects the project to a remote repository (GitLab, GitHub…), for history and multi-person work. It needs server mode: in browser mode, the tab says so and offers nothing else.
Export — Download ZIP: the complete tree, ready to be archived, sent, or re-imported elsewhere. It is the simplest gesture, and often enough — archiving a project’s state at submission time, passing work to a colleague. It works in both modes.

A project pushes, but does not pull yet

For a project, syncing goes one way only. You push your changes to the repository; changes made on the remote — by a colleague, for instance — cannot be brought back automatically. A banner in the Git repository tab says so. Item-by-item pulling has been disabled: on a project, which mixes dashboards, cohorts, scripts and datasets, it reported phantom changes and overwrote local work.

To start again from what the repository holds, Settings › Reinstall rebuilds the whole project from the repository. It is all or nothing — anything not pushed is lost —, and reserved to whoever can delete the project.

The rest is common to every entity

Connecting a repository, choosing a branch, selecting the files to push, and choosing between one repository or one per element: all of it works the same way for a project, an ETL pipeline or a workspace, and is described once and for all in Git versioning and Import and export.

What does not leave

Patient data — unless explicitly marked, file by file —, connection passwords and tokens, and execution results: a cohort’s count and its attrition depend on the database queried, not on the definition, and every installation recomputes them.

The pipeline is not versioned either

The diagram on the Pipeline page stays local as long as its execution does not exist.

Importing a project

A ZIP re-imports, and a git repository clones. You get back cohorts, dashboards and scripts. Databases, on the other hand, do not travel: the project only carries a pointer to each one, and the import links it to the matching database if the receiving instance has it. Otherwise, you link your own.

That is what makes a Linkr project genuinely reproducible: a colleague in another hospital replays your approach on their data, without yours ever leaving your institution.

Going further

Git versioning — the repository, pushing, and choosing one repository per element.
Import and export — both ways out, and what an archive holds.
Datasets — marking a data file for versioning.
Publishing content — going beyond project-to-project sharing.