📘

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.

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 the export directory in your Gigantum working directory.

• 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

• 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 from gm.workspace.
  • Click on the Migrate button and then confirm the migration.

• 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