SnapshotCM snapshots capture the complete state of a software system's source and make snapshot-level operations trivial. Importing from your current version control (or configuration management product)into the equivalent SnapshotCM structure is possible with a little care. In fact, since SnapshotCM saves more information than most systems, nearly all of your current information can be preserved during an import.

The first question to ask is "What shall I import?". The initial answer, everything, is certainly possible. However, everything is not necessarily useful, and will take more time than other options. In the end, you need to decide. The following describes viable approaches to consider.

Option #1 - Import Everything

Importing all history, including all file content revisions, change comments, change dates and times, and change authors is supported by the trueimportrcs.sh script for RCS and SoftBench CM RCS based files. The trueimportrcs.sh script maps RCS symbolic names to snapshot names, and the current, main-line revision to the "Current" mapped snapshot. To use trueimportrcs.sh, there are a few steps required:

1. Arrange the RCS files to import into a hierarchy, with the file and directory names being what you wish them to be in SnapshotCM (the trailing ",v" will be ignored). The trueimportrcs.sh script does not support renames, but gives all files the same names in all snapshots.
   Notes: NONE of the files being imported should exist in any of the release snapshots. Directories will be created as necessary. Empty directories are not imported.
2. Create a SnapshotCM project with one release snapshot. We recommend calling the release snapshot "Current", but you can use any name that does not conflict with a symbolic name used in an RCS file. To create a new project, select "Project->Create" from the GUI, or from a command prompt, run

   sscreate -h serverHost /Project/Current

3. If you want to customize the ACL for the project and its snapshot, now is the easiest time, as all snapshots created below will get their initial ACL from the project ACL. See the Administration Guide for more information on setting ACLs.
4. Map the RCS hierarchy as a SnapshotCM workspace to the release snapshot just created. Run:

   wmap add

   and follow the prompts to create a new workspace mapping.
5. From the root of the workspace containing RCS files, run trueimportrcs.sh:

   trueimportrcs.sh . | tee script | sh 2>&1 | tee output

   The dot says to import all RCS files recursively from the current directory. The script file captures the generated shell script which sh executes. The output file captures output for later examination.

   NOTE: trueimportrcs.sh is a unix shell script containing several customizations. One customization filters the set of symbolic names for which snapshots will be created. Search for CUSTOM in the script for further details.

6. Once completed, the SnapshotCM project you imported into will contain a snapshot for every symbolic name in any RCS file. Each snapshot will reference the same revision as the corresponding symbolic name in RCS. Files without a given symbolic name will not exist in that named snapshot.
7. At this point, or even while the import is going on, you can create appropriate relationships between the release snapshots. Don't delete or rename or modify the content of any snapshot during the import or something is likely to fail. But it is OK to create and delete relationships.
8. Once proper relationships are established between the release snapshots and the import is completed, you can compare related snapshots. Files which were tagged for earlier releases, but not later releases, will show up as changes wanting to propagate into later releases. Two situations are common:
   1. Such files may be obsolete, in which case you can customize individual file or directory propagation to represent the delete in SnapshotCM (or simply freeze the target snapshots so inadvertent propagation does not occur).
   2. If you've used tag lists to represent a release state rather than fully tagging each release (something supported by HP's RCS and SoftBench CM products, for example), you can propagate those changes forward so that each snapshot is fully populated. Note: An alternative is to fully populate the tags of interest in RCS before the import.
   3. You may have some of both situations, and will need to decide for each file which it is to be. If you have an automated means of determining which situation applies, you can automate the copying forward of appropriate changes by use of the ssupdate command.

Option #2 - Discrete State Import

Since snapshots capture distinct states of a software system and provide efficient methods for comparison, another approach is to import only past states of specific interest. For example, if you have two previous releases plus current development, one might import into three snapshots: R1, R2 and current. Discrete state import is more complicated, but may be both more useful and faster, than a complete import.

The steps proceed as follows:

1. Create a SnapshotCM project with a single snapshot, call the snapshot Current:
   • From the Windows GUI, select Project -> Open Project Manager....
   • Select your server and press New....
   • Enter a project name and description of your choice.
   • Enter Current as the initial snapshot name.
   • Select OK.
2. Using your old system, create a complete hierarchy of files representing Release 1.
3. Using SnapshotCM, setup the Release 1 hierarchy as a workspace mapped to the Current snapshot.
   • Identify the directory representing the root of the hierarchy to import into Current. Paths within this hierarchy will become the paths to the files within SnapshotCM. Although the hierarchy can be renamed or moved around later, getting it the way you want it at first is always best.
   • If you are on Windows, use the GUI to create the workspace:
     1. Select Snapshot -> Map To Workspace, select the just created project in the Project list, then the Current snapshot from the Snapshot list, then select Next.
     2. Specify the directory representing the root of the hierarchy to import as the Local Folder. You may choose any unused name for the workspace, though the default is recommended. Select Next.
     3. In the working set dialog, simply select Next.
     4. In the summary dialog, review your selections, and if correct, select Finish to create the workspace.
   • If you are not on Windows, or prefer to use the command line, use the wmap command to create a mapping:
     1. Set your working directory to the directory representing the root of the hierarchy to import.
     2. Run the following wmap command, filling in the server and Project values for the project created in step 1:

        wmap add -NCurrent -hserver -S/Project/Current -D. -r/

4. From the root of the workspace, perform a recursive check in of all files and directories.
   • From the Windows GUI, open the workspace browser on the Current workspace, select all the local files and directories to import, then select the menu File -> Check In.... In the check in dialog, select the recursive and create options, enter a comment to apply to all files imported, and select OK.
   • If not on Windows, use this wci command from the root of the workspace:

     wci -auto -R -C. -sDate .
     

     where -auto says to allow create and automatically determine the text/binary status of each file, -R says to import every file recursively, -C. says to not prompt for a comment, and Date specifies the date to use for each revision created. Note: the date option is not (yet) available from the GUI.
5. Once Release 1 is imported into Current, create a copy of Current called R1 as follows:
   • From the Windows GUI, open your project if necessary (using Project -> Open) and select Current. Now select Snapshot -> New -> Release Snapshot, enter R1 as the new snapshot name, make certain that Insert before is selected, and press OK.
6. If you are only importing one release, import is complete. The initial revision is in snapshot R1, and Current is ready for on-going development.
7. Otherwise, it is time to repeat the process for the next release, with some changes to account for the additional complexities. If you have files or directories that have been renamed in the next release, you will need to use wrename to make analogous changes to the Current snapshot that correspond to changes in the workspace. It is typically easier to apply rename changes before checking in file content changes.
8. Now update the workspace (using your old tools) to represent Release 2. The goal now is to check in all new files and files which are different between the workspace and Current, and do nothing with the files which are unchanged between Release 1 and Release 2. Renames are assumed, at this point, to have been taken care of by hand.
   1. Run

      wset -l -R -t "Import for Release 2" .
      

      from the root of the workspace to set locks on all files in the snapshot.
   2. Now, for each file, run

      wdiff -K file
      

      If there are no differences, run

      wset -u file
      

      to remove the lock. On Unix, this can be automated by running the following command-line from the root of the workspace:

      wls -RL1 | sed -e 's:^M::' -e 's:.*:wdiff -K "&" \&\& wset -u "&":' >../script
      

      and then executing ../script. Note: the -K option to wdiff causes keyword expansion value differences to be ignored. This insures that any keyword editing that SnapshotCM might do will not show up as differences.
   3. Now, check in all modified and new files by running the same wci command as before:

      wci -auto -R -C. -s NewReleaseDate  .
      

   4. Now, all files which remain and which are locked exist in the snapshot but not in the workspace, so delete them from the snapshot:

      wls -R -L -1 >List
      # As a sanity check, verify that all files in List are really not in workspace:
      xargs -e "" --no-run-if-empty ls < List 2>/dev/null # Linux version, should have no output
      xargs -e "" -n20 ls < List 2>/dev/null              # HP-UX version, should have no output
      wset -R -u .
      xargs -e "" --no-run-if-empty wremove < List        # Linux version
      xargs -e "" -n20 wremove < List                     # HP-UX version
      rm List
      

   5. At this point, the workspace and snapshot should be identical. Verify this by running

      wdiff -R -K .
      

      in the workspace. Note: Files containing recognized SnapshotCM keywords and for which keyword expansion are enabled are not truly up-to-date because of the changed expansion values, a fact which is known to SnapshotCM. Workspace updating operations recognize this and will refresh all such files.
9. Repeat steps 5 through 9 until Current represents the current state of development.

Each of the migration options has its advantages and disadvantages, and the various options and sub-options can be combined. Which is best depends on various constraints of time, disk space, complexity, project state, etc.

Preserving Historical Author Information

trueimportrcs.sh provides two methods for preserving author information during import:

1. Prepend the author information to the comment string for each revision. trueimportrcs.sh uses this method as the default.
2. In SnapshotCM, history records contain the ID of the account making the change. So you could create accounts for all the users (configuring yourself to be able to login to each such account without a password) and set the SNAPSHOTCM_ACCOUNT=user environment variable appropriately for each wci command. For this to work, you will need to have enough licenses for the number of different accounts you will create (or suffer the performance penalty). A newly initialized database provides 200 licenses for 6 weeks, so this probably will not be a problem for most users. If it is a problem, a higher limit temporary license can be issued. trueimportrcs.sh uses this mode of operation when passed the -A option.