Lab Upstream Workflow

This guide is for labs that want to modify ScanImage source code for their own purposes while still receiving official bugfixes and new releases from Vidrio. It uses Git’s concept of a remote named upstream to keep the two separate.

If you prefer a graphical interface, see Lab Upstream Workflow (SourceTree).

When You Need This

The default workflow — checking out a minor/{version} branch and running git pull — is ideal for most labs. You get bugfixes automatically and everything stays synchronized with the official release.

You need the upstream workflow when:

You want to modify ScanImage source files (e.g. custom acquisition modes, altered UI panels, lab-specific hardware drivers)
You need those modifications to persist across bugfix updates
You want different lab members to independently manage their own version of these customizations

Concept

[vidriotech/scanimage-*-releases]  ← upstream (read-only, official)
        |
        |  git fetch upstream
        ↓
[Your private repo or local branch]  ← origin (your lab's customizations)
        |
        |  each lab member clones this
        ↓
[Individual member's working clone]  ← on their machine, on their MATLAB path

Your private repository holds your customizations. The official releases repository is the upstream source of truth. You merge upstream fixes into your lab repo on your own schedule.

Setup

Option A — Start fresh from this repository (recommended)

# 1. Clone the release repository locally
git clone https://<username>:<token>@gitlab.com/vidriotech/scanimage-basic-releases.git scanimage-lab
cd scanimage-lab

# 2. Rename the remote so 'upstream' refers to the official releases repo
git remote rename origin upstream

# 3. Create a local bare repository to act as your lab's private remote
#    (Choose any path on your machine or shared network drive)
git init --bare /path/to/your/lab-scanimage.git
git remote add origin /path/to/your/lab-scanimage.git

# 4. Push to your local bare repository
git push -u origin main

# 5. Create a branch for your lab's customizations
git checkout -b lab/<labname>/custom
git push -u origin lab/<labname>/custom

Note

What does it mean to have a local bare repository as your remote? It stores your full commit history and can be pushed to and pulled from just like a remote server, but lives entirely on your local machine or a shared network drive without duplicating storage of all of the source files to that location (bare). No GitHub or GitLab account is needed. If your lab members share a network drive, point the path there so everyone can clone from the same location.

Alternative: Use a remote private repository (GitLab/GitHub)

If your lab requires access from multiple machines that do not share a network drive, you can host your private repository on GitLab or GitHub instead:

# Create an empty private repo on GitLab/GitHub first, then:
git remote add origin https://gitlab.com/<your-org>/<your-repo>.git
git push -u origin main

Warning

License compliance — Your ScanImage license is granted to your lab only. Do not make this repository public, and do not share access with anyone who has not purchased a ScanImage license. Sharing ScanImage source code with unlicensed users — even indirectly through a repository — violates your license agreement. Keep the repository strictly private and limit access to licensed members of your lab.

Tip

Interested in sharing your customizations with the ScanImage community? If your lab has developed extensions or modifications to ScanImage that you believe would benefit other users, reach out to us at support@mbfbioscience.com. We review community contributions and may be able to host your customized version directly in our official releases repository, making it available to all licensed ScanImage users in a way that is fully compliant with the license terms.

Option B — You already have a clone and want to add this repo as upstream

# From inside your existing local clone:
git remote add upstream https://<username>:<token>@gitlab.com/vidriotech/scanimage-basic-releases.git
git fetch upstream

Making Lab-Specific Customizations

Work on your lab/<labname>/custom branch (or any branch in your private repo). Commit and push as you normally would to origin.

Practical tip: Where possible, keep your customizations in separate files from core ScanImage files. If your changes live in new files (e.g. +lab/myCustomPlugin.m) rather than edits inside existing ScanImage files, merging upstream bugfixes will rarely produce conflicts.

Receiving Official Bugfixes and New Releases

When Vidrio pushes a fix to minor/{version} or a new major release to main, bring it into your lab branch:

# Fetch the latest from the official repo
git fetch upstream

# Merge the patch branch (or a specific tag) into your lab branch
git checkout lab/<labname>/custom
git merge upstream/minor/2023b

# Resolve any conflicts, then push to your private repo
git push origin lab/<labname>/custom

Each lab member then pulls from origin to receive both the upstream fix and any lab customizations:

git pull origin lab/<labname>/custom

Multi-Member Lab Workflow

Each lab member maintains their own clone of your private repository on their own machine. They check out the lab branch and add that folder to their MATLAB path.

# First-time setup for a new lab member:
git clone https://<username>:<token>@gitlab.com/<your-org>/<your-repo>.git scanimage
cd scanimage
git checkout lab/<labname>/custom

Because each person’s clone is on their own machine, one member modifying source code does not affect any other member’s running instance. Members who do not want any customizations can simply check out the official minor/{version} branch directly from upstream instead.

Caveats

Merge conflicts: If your customizations edit the same lines in the same files as an upstream bugfix, Git will flag a conflict for you to resolve manually. This is uncommon if you keep customizations in separate files, but is worth being aware of.
Storage: Your private repository stores only your commits on top of the official history. It does not duplicate the full ScanImage history unless you push the entire branch history to your private repo, which is normal and expected.
Access tokens: The upstream remote in your local clone requires your Vidrio deploy token. If your token is renewed, update the remote URL:
```
git remote set-url upstream https://<username>:<new-token>@gitlab.com/vidriotech/scanimage-basic-releases.git
```