In short
Any entity — a project, an ETL pipeline, a concept mapping, a workspace — can be linked to a git repository to keep a history and work as a team. The mechanism is identical for all nine types. The decision that matters: version a workspace as one block, or give each element its own repository and its own pace — the workspace then holding only a pointer to each.
Why git
Health-data work runs for months and changes constantly: an inclusion criterion is refined, a script is fixed, a figure is redone. Without a history, two questions go unanswered — “what changed since the March analysis?” and “who modified this criterion, and why?”
Git answers both. Linkr uses it without asking you to know it: the commands are buttons, and the versioned files are your entities, not code.
What git concretely brings here
A dated, signed history of every change, the ability to go back, and several people working on the same content without overwriting one another. If these notions are new, see Versioning and collaboration.
What gets pushed is exactly what a ZIP archive holds: the same tree of text files. Both ways out are described in Import and export; this page covers the second.
Linking an entity to a repository
From an entity’s menu — the three dots on its card —, Versioning opens a window with two tabs, Git repository and Export.
While nothing is linked, the Git repository tab shows a connection form: the Repository URL, and an access token if the repository is private. Linkr verifies the remote before saving and detects the branch.
Where to find an access token
On GitLab: Preferences › Access Tokens, with the read_repository and write_repository scopes. On GitHub: Settings › Developer settings › Personal access tokens, with the repo scope. The application recalls these paths under the field.
The token stays confidential
It is saved for you, per host, and reused across every repository on that host. Other users never see it, the interface never returns it, and it appears in no export and in no repository.
Once linked, the tab reduces to a single line: the repository address, a badge if it is private, and the means to edit the token or disconnect.
Syncing
Two tabs organise everyday work.
Quick actions
A Sync all button commits and pushes everything that changed, with a commit message written for you. It lists what will be pushed before acting.
This is the common case: you worked, you sync, you are done.
Details
The file-by-file view, to choose what leaves. Each modified file appears with a plain description of what it holds — “A cohort definition (its inclusion/exclusion criteria)” — and its diff can be inspected.
Use it when only part of the work is ready to be shared.
Pull before you push
If the remote holds changes you do not have, Linkr refuses to sync and says so: “The remote has changes you don’t have yet — pull them before pushing, or your push would overwrite them.” That is what stops you overwriting a colleague’s work.
Pulling other people’s work
The pull panel lists what changed on the repository side, and you choose what to apply. A diff can be inspected before confirming, which lets you see that a cohort gained a criterion before accepting it.
One workspace, or each element separately
This is the structural decision, and it deserves to be made knowingly. A workspace holds projects, ETL pipelines, schemas, concept mappings. Two arrangements are possible — and they combine.
One repository for everything
The workspace carries its elements in full.
One repository, one history. Simple to set up, and enough for a workspace that lives as a single piece.
One repository per element
Each element has its own repository and cycle.
The workspace keeps only a pointer to each. This is the recommended arrangement as soon as elements evolve at different paces.
What the pointer changes
Linking an element to its own repository changes what the workspace carries about it. The export tooltip says so: “Only metadata and the Git link are exported — the full content stays in the linked Git repository.”
Concretely, the workspace export then holds, for that element, only an identity card and its repository address. Whoever imports the workspace gets the list of its elements, and Linkr clones each linked repository to reconstitute the content.
Why this is the recommended arrangement
An ETL pipeline and an analysis project do not evolve at the same pace: the first settles down, the second changes weekly. With a single repository, every change to one clutters the other’s history, and it becomes impossible to say “give me the pipeline version used for the paper”.
Separate repositories give each element its own history, its own versions and its own licence — and let it be published on its own, without carrying the rest of the workspace along.
Mixing is normal
The decision is made element by element, and nothing requires uniformity. At export time Linkr looks at each element: if it is linked to a repository, it writes a pointer; if not, it writes its content.
| The element is… | In the workspace export | In its own export |
|---|---|---|
| linked to a repository | Metadata + the repository address. | Its full content. |
| not linked | Its full content, nested in the tree. | Its full content. |
A typical workspace therefore ends up mixed: the ETL pipeline and the OMOP schema, shared and publishable, each have their repository; the ongoing projects, specific to the team, travel inside the workspace.
A linked element's own export does carry everything
A frequent confusion: exporting an element from its own window always produces its full content, linked or not. Only workspace exports reduce it to a pointer.
On import, a private repository asks for a token
Importing a workspace clones the linked repositories without presenting credentials. Private ones therefore stay empty, and Linkr lists them in a panel: you enter an access token and load each with a Clone button.
What never leaves
Three things stay with you, whichever arrangement you choose.
Patient data
Excluded by default, along with the edit journal that goes with it. A file travels only if you mark it explicitly.
Passwords and tokens
Hosts, ports, accounts, passwords: none of it leaves the machine. Whoever picks the content up declares their own connections.
Execution results
A cohort’s count, its attrition: they depend on the database queried, not on the definition. Every installation recomputes them.
The format makes diffs readable
Because entities are written as text files, a comparison tool shows exactly what changed between two versions. An added inclusion criterion reads as one line — which no binary format would allow.
Going further
- Import and export — the other way out, and exactly what an archive holds.
- Publishing content — from repository to catalog entry.
- Versioning a project — precisely what a project carries.
- Versioning and collaboration — the principles, if git is new to you.