Lab Upstream Workflow (SourceTree)

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.

This version of the guide uses SourceTree as the Git interface. If you prefer working in a terminal, see Lab Upstream Workflow.

When You Need This

The default workflow — checking out a minor/{version} branch and pulling — 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)
        |
        |  Fetch from 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 B — You already have a clone and want to add this repo as upstream

  1. Open your existing local clone in SourceTree.

  2. Go to Repository > Repository Settings > Remotes.

  3. Click Add.

  4. Set Remote Name to upstream.

  5. Set URL / Path to your release repository URL with credentials:

    https://<username>:<token>@gitlab.com/vidriotech/scanimage-basic-releases.git

  6. Click OK.

  7. Click the Fetch button in the toolbar. Check Fetch from all remotes and click OK.

Making Lab-Specific Customizations

Work on your lab/<labname>/custom branch. To commit and push changes:

  1. In the File Status panel, modified files appear under Unstaged Files.

  2. Check the box next to each file you want to include, or click Stage All.

  3. Enter a commit message in the text box at the bottom.

  4. Click Commit.

  5. Click Push to send your commits 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:

  1. Fetch from upstream: Click the Fetch button, check Fetch from all remotes (or select just upstream), and click OK. This downloads the latest from Vidrio without changing any of your files yet.

  2. Check out your lab branch: In the left sidebar under Branches, double-click lab/<labname>/custom to check it out.

  3. Merge the upstream patch branch:

    • In the left sidebar under Remotes > upstream, find the branch you want (e.g. minor/2023b).

    • Right-click it and select Merge upstream/minor/2023b into current branch.

    • If there are no conflicts, the merge completes automatically.

    • If there are conflicts, SourceTree highlights them in the File Status panel. Right-click a conflicted file and choose Resolve Conflicts to open your merge tool, or fix the file manually and then right-click and choose Mark Resolved.

  4. Push to origin: Click Push, select origin, check your lab branch, and click Push.

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

  1. Check out the lab branch by double-clicking it in the left sidebar.

  2. Click Pull. SourceTree will pull from origin by default.

Multi-Member Lab Workflow

Each lab member maintains their own clone of your private repository on their own machine. To set up a new member:

  1. Open SourceTree and click Clone.

  2. In Source Path / URL, enter the path to the shared bare repository (e.g. \\networkdrive\lab-repos\lab-scanimage.git) or the HTTPS URL if using GitLab/GitHub.

  3. Set the Destination Path to where they want ScanImage on their machine.

  4. Click Clone.

  5. In the left sidebar, find lab/<labname>/custom under Remotes > origin. Double-click it to check it out as a local branch.

  6. Add the ScanImage folder to their MATLAB path.

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: SourceTree highlights conflicted files in the File Status panel with a warning icon. Right-click a conflicted file to open it in your configured merge tool, or edit it manually and then right-click and choose Mark Resolved. This is uncommon if you keep customizations in separate files.

  • 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: If your Vidrio deploy token is renewed, go to Repository > Repository Settings > Remotes, select upstream, click Edit, and update the URL with your new token.