In short
An entity moves around through two mechanisms, and only two: the ZIP archive, which you download and drop back in, and the git repository, which you push to and clone from. The catalog is not a third one: it is a directory of git repositories, and installing an entry amounts to cloning its repository. The gesture is the same for all ten entity types.
Two ways out of Linkr
Every entity — a project, a schema, an ETL pipeline, a plugin — is handled from its card menu, the three dots at the top right. Two entries there, Export and Versioning, lead to two distinct routes, and which one you want depends on what you are doing.
Export
A ZIP file, right now.
To archive a state, email a piece of work, attach an appendix to a paper. A snapshot, with no follow-up.
Versioning
A git repository, over time.
To keep a history, work as a team, publish. You push straight from Linkr — no archive to produce.
Versioning does not go through the ZIP
Both entries open the same two-tab screen, Git repository and Export — a window for most entities, the Versioning & export page for a project and for the workspace. Two possible ways out in one place, not two steps of one operation. To version, you link the entity to a repository and push — you never download an archive in between.
What is sent is the same either way: the same tree of text files. See Git versioning.
What the archive contains
The ZIP is named after the entity. It is a tree of text files, not an opaque binary format: you can open it, read it, drop it into a repository yourself, attach it to a paper.
.gitignore
**/*.csv**/*.parquet**/*.pq**/*.xlsx**/*.xls**/*.edits.json.cache/!datasets/ventilation_collection/ventilation_collection.csv!datasets/ventilation_collection/ventilation_collection.edits.json
Data files stay behind
An export does not contain your data, and that is deliberate: sharing a dashboard must never distribute patient records by accident.
The exclusion covers data file extensions — CSV, Parquet, Excel — and the edit journal that goes with them. A project’s Export tab says as much: “Data files are excluded by default for security. To include a specific dataset, mark it ‘for versioning’ in the Datasets sidebar (right-click).”
That is the whole method: there is no global switch that would carry everything. You mark files one by one — right-click a dataset, Mark for versioning — and a badge then flags those that will travel.
Marking a file also carries its edit journal
Your cell corrections travel with the file, never separately. That is consistent: for a hand-filled collection the original file does not change, and the typed values exist nowhere but that journal.
Connection credentials never leave
No password and no access token appears in an export, and no option can put one there. Hosts, ports, database names, accounts: none of it leaves the machine.
An exported database carries its name and its schema mapping — not a single row of data. Whoever imports it declares their own connection and points it at their own files.
Exporting a whole workspace
A workspace exports in one piece, from its Versioning & export page, Export tab. One checkbox per section, the warehouse sections grouped, and for projects, mappings and ETL pipelines one checkbox per item: you can leave one out.
Export
Download your workspace content as a ZIP archive. Select which sections to include. Connection details and passwords are never exported; data files are included only when marked for versioning.
Full project content: README, scripts, dashboards, cohorts, pipeline. Dataset files are included only when marked for versioning.
All wiki pages (Markdown), their tree structure and attachments.
Database entries: names and schema mappings. Connection details and passwords are never exported.
Full ETL pipelines with all their files. Data files are included only when marked for versioning.
A git-linked entity is not copied into the archive
If an item is linked to a remote repository, the workspace export carries only its metadata and its link — its content stays in its repository. The tooltip says so: “Only metadata and the Git link are exported.”
Exporting that entity on its own, by contrast, includes all of its content. The reduction to a pointer applies to workspace exports only.
Importing
A list page’s Import button opens a window with three tabs. The first two are the two mechanisms; the third is a shortcut onto the second, since the catalog points at git repositories.
Import
Import from a ZIP file or clone a Git repository.
- Upload ZIP — an archive exported from Linkr, dropped or picked. Works in both modes.
- From Git — a remote repository, cloned on the server; the entity stays linked to the repository. This tab disappears when the entity is already linked to a repository.
- From the catalog — the catalog filtered to the type you are importing, present only for types the catalog knows. Installing clones the entry’s repository: server mode required.
The From Git tab expects three fields: Repository URL, Branch, and Token — the last one only for a private repository. Then Clone & import.
Clone error messages are specific — read them
They distinguish four causes, which saves you looking in the wrong place: repository not found (the URL), branch not found (the branch name), authentication failed (the token), network error (the connection or the proxy).
When the item already exists
This is the everyday situation as soon as several people work together: you re-import an entity you already have. Linkr does not decide for you — an Item already exists window leaves you the choice.
Item already exists
An item named "OMOP CDM 5.4" already exists. What would you like to do?
- Create copy — both versions coexist. Pick this to compare, or when you are not sure you want to lose the existing one.
- Overwrite — the imported version replaces yours. Pick this when the import is authoritative: you are pulling back a colleague’s reference version.
Re-importing the same entity updates it rather than duplicating it
Every entity carries a lineage identifier that follows it from one installation to another. That is what lets Linkr recognise the same entity coming back modified, rather than a new one. See Entities and sharing.
What the import tells you
An import rarely succeeds in complete silence, and the messages are worth a glance.
- Linkr too old — “This content needs Linkr 2.4.3 or later…”: the entity was exported in a format your version cannot fully read. The import is refused before anything is written, rather than leaving a half-read entity. Update Linkr, then import it again.
- Format issues — the entity is imported, but Linkr found departures from the expected format. The message gives their number. A project produced by an older version, or edited by hand, often goes through this.
- Git-linked items whose content is missing — an imported workspace may contain entities reduced to their pointer, whose repository is private. A panel lists them, you enter an access token, and load each one with a Clone button.
- Imported without its organization — the linked organization could not be created for lack of permission. An administrator adds it, then you link it from the workspace settings.
Importing into a project overwrites its current files
From an existing project’s Import tab, the warning is explicit: “This will overwrite the current project files.” To keep both, import as a new project instead.
What changes between modes
Server mode
All three origins work.
Cloning runs on the server, which gives access to private repositories and to the catalog.
Browser mode
The ZIP works; git cloning and installing from the catalog do not.
Both mean cloning a git repository, which the browser alone cannot do. You can still browse the catalog.
See Deployment modes to know which one you are running.
Going further
- Community catalog — installing content published by other teams.
- Publishing content — preparing an entity so others can reuse it.
- Git versioning — the git repository, and what leaves a project.
- Entities and sharing — why all ten types export the same way.