Castellum User's Manual

1. About

Castellum is an application that allows migrating source-code repositories from Microsoft SourceSafe to Git repositories.
All files and history of each file are migrated to new repository.
More info can be found on the Product Page

2. Requirements

• Should have installed Microsoft .NET Framework 4.7.2+
• For achieving better performance on large repositories, you should run Castellum on the same machine where SourceSafe repository is hosted (this avoids network bottlenecks), or you can just copy the VSS repository to your local
• Doesn't require anymore Microsoft SourceSafe to be installed (the tool read directly from files bypassing VSS API). Don't even need admin password
• Target Git repository can be accessed through file-sharing or through https/git protocols

3. VSS Repository Preparation

• All examples from this document use C:\VSS as the Source Safe repository folder (source)
• Suggestion: Ask your users to check-in every file that is checked-out
• Suggestion: Make a back-up of your repository folder¹, and run Castellum using this back-up copy.
• Suggestion: In case you are running using a live repository (non back-up), disable file-sharing so that no user will be able to use SourceSafe while migration is running
• Important: You should run SourceSafe ANALYZE.EXE utility, against your VSSCopy repository.
  e.g.: C: \Program Files\Microsoft Visual SourceSafe\analyze.exe –f C:\VSS\data
  
  Analyze executes 4 steps and may be a little slow depending on the size of your repository.
  

4. Git Repository Preparation

Ensure that Git repository is hosted in the same machine as SourceSafe

• All examples from this document use C:\GIT as the Git repository folder (target)
• In case you don’t have a repository, you can create an empty folder, and Castellum will initialize a blank repository for you.
• In case you already have a git repository in a different machine, you can just copy it² into the machine where SourceSafe is hosted

5. Temporary Folder

Create a temporary folder for the migration. You should have enough space to hold all tour VSS data.

If you use a RAM DRIVE you'll notice significant speed improve

All examples in this document use C:\TEMP as the Temporary Folder

6. Installation

Just run the installer (Castellum-1.0.0-Trial-Setup.exe).

If you don't want a regular installation, or don't have Administration privileges, just unzip Castellum-1.0.0-Trial.zip into any folder, extracting all contents (Castellum.exe and other necessary DLLs). E.g.: C:\Castellum

Running Castellum

It's not necessary to have Administrator privileges for running Castellum, but you should have full read access to SourceSafe repository and full write access to Git repository

• Suggestion: Before running Castellum, it's strongly recommended to stop Windows Search Indexing service.
• Execute Castellum.exe (which should be available in Start Menu, under Castellum folder)

Step 1. Choose a Temporary Folder

Choose a Temporary Folder

 

Step 2. Choose a Source Safe Repository (source)

• Choose a Source Safe Repository, by locating your srcsafe.ini file.
• Input user name and password, or leave Admin user and click Clear Admin Password button, which will set empty password for Admin user

 

Step 3. Choose Folders to Export

• Choose which folders you want to Migrate
• Don't worry if you have files files that were branched from other folders - our tool will read all past history (will traverse through branch origin)

 

Step 4. Choose Export Options

• "Remove SCC" define whether Source-Control-Mapping files should be ignored (*.scc, *.vssscc, *.vspscc) and Source-Bindings should be removed from Microsoft Visual Studio.NET files (*.csproj, *.vbproj, *.sln)
• "Ignore Visual Studio.NET user-specific settings" define whether Microsoft Visual Studio.NET user-settings files should be ignored (*.suo, *.user)
• If binary file is larger than xxx kB, migrate only latest version: if a binary file surpasses size limit, only the latest version of this file will be imported. Useful for ignoring history of binary DLLs or EXEs
• If binary file is larger than xxx kB, dont migrate file at all: if a binary file surpasses size limit, it will not be imported at all. Useful for ignoring huge binary files which shouldn't be in Source Safe at first place.

 

Step 5. Exporting files from VSS

In this step, Castellum will read every file that should be imported, including its history.
Every file revision will be compressed into zip packages

 

Step 6. Exporting More VSS Folders

If desired, you can repeat Steps 2 to 5 as many times as you want. This allow you to export a huge VSS repository in many parts, avoiding Ouf Of Memory problems.
Also it enables you to merge two different repositories, as in cases when one repository keeps old projects and the other current ones, or just when projects were split across multiple VSS repositories to workaround VSS size limits.

 

Step 7. Choose a Git Repository (target)

• Choose a Git Repository, by locating GIT folder (which is the one which contains .git subfolder)

 

Step 8. Choose a Target Folder for Import

If the target repository is empty, you will see only the root folder, as in the previous screenshot.

 

Step 9. Import

• Every zip package (created in steps 2 to 5) will be reindexed
• Duplicates are deleted (in case the same folder was extracted more than once in different exports)
• Individual file changes will be grouped into changesets, according to the time file changes happened (inside short time interval), and according to the author of each change. In the example below, all file-histories were grouped into only 937 changesets.
• Changesets will be commited to Git

 

Step 10. Final Step

After all changesets are commited to Git, no files are not deleted automatically. By opening Temporary folder, you'll be able to see

• Castellum*.log: log of every file which was imported or ignored
• *.zip: each package consists of many sourcesafe files and their respective histories.
• Changesets*.xml: each xml describes the contents of the given changesets which happened during a specific month (one xml for each month)

All of those files/folders can be deleted.