Key Points
- New format for Projects improves branching structure, which requires a migration
- Only one branch is migrated and kept in a project for simplicity and consistency
- You may need to coordinate with collaborators to re-import after you migrate
- Only the owner of a Project can migrate
Contact Support for Assistance
If you desire assistance during the migration process, please email [email protected] or join our Spectrum Chat
Why is Migration Necessary
Migration is required for Projects created using Gigantum Client 0.10.4 and earlier. Any Dataset or Project created with Gigantum Client 0.11.0 or newer does not need to be migrated.
While we strive to minimize disruptive changes, in Gigantum Client 0.11.0 several important changes were made that require a migration:
- The branch structure was greatly simplified and migration is needed to the new format. See the
Use Branches section for more information - An "untracked" directory is now available in the
output
section of a Project. Files written here won't be versioned or synced. - Project internal metadata structure was improved
Migration Process
Merge Branches Before Migration
If you are an advanced user that has taken advantage of branching prior to 0.11.0 release, you should be 100% sure that you merge all work you wish to keep back to the workspace branch prior to migration.
You will see a large banner at the top of a Project that needs to be migrated.


A project that needs to be migrated.
The migration process will create a branch called master
from the current branch when the "Migrate" button is clicked and confirmed. You will be able to review changes before they are applied. Remember, all of the content you want to keep must be in your current branch.
If you are the owner of the Project (you created it, you're not a collaborator), you can migrate the Project using the steps below:
-
(Recommended) Export Project to create a backup
- Click
Export
in the Project actions menu in the top right corner of the page. This will effectively create a back up zip file in case something goes wrong during migration that is available in theexport
directory in your Gigantum working directory.
- Click
-
Merge Branches If Needed
- If you previously had content in branches that were not the primary "workspace" branch, you should merge these branches into
gm.workspace-<your username>
. - If you didn't use the old branching functions in your Project you can skip this step
- If you previously had content in branches that were not the primary "workspace" branch, you should merge these branches into
-
Migrate Project
- Ensure you are on the branch with your latest changes. For most Projects this will be
gm.workspace-<your username>
.- For the special case where you have just imported a Project from a zip file,
gm.workspace-<your username>
most likely won't exist and instead you should migrate fromgm.workspace
.
- For the special case where you have just imported a Project from a zip file,
- Click on the Migrate button and then confirm the migration.
- Ensure you are on the branch with your latest changes. For most Projects this will be


The confirmation window that will be displayed
- Notify Collaborators
- If you have Collaborators on your project, you should notify them that the project has been migrated. The easiest thing to do is for all collaborators to simply re-import to get the latest version.
I'm not the Project owner, what do I do?
Only the owner of a Project can trigger a migration it since this operation is irreversible. Once the Project owner migrates the project and you sync, the new master
branch will now be available. You may still be lingering on an old branch when this happens.
If you don't have any changes on your branch that you wish to keep, you should simply switch to master
, or create a branch from master
and continue working. You should also delete the old branch (should start with gm.workspace-
) to finish cleaning the project up.
If you have changes on your branch that you want to keep. You should:
- Merge
master
into your branch - Create a new branch from your branch, giving it a reasonable name
- Switch to your new branch
- Delete your old branch
Updated about a year ago