SnapshotCM Tips and Tricks

Splitting a Project

A few weeks ago, we received an e-mail asking if it was possible to copy a release snapshot from one project into another. As is so often the case, the simple answer is yes. The more complete answer must first ask what you are trying to accomplish.

In this case, the goal was to split a project, pulling part of the source code into a separate project to facilitate sharing that code among multiple projects. For this, there are two steps: First, copy the files into their own project, and second, remove them from the original location (if desired).

Populating the New Project

After creating the new project, you will have an empty snapshot. To populate it, simply select the source snapshot, and choose the "Snapshot -> Copy Changes To..." menu. In the resulting dialog, edit the target snapshot field to contain the full path to a snapshot in the new project. Tab out of the field and all files in the original snapshot will be shown. Uncheck all files, check just the files to copy and then "Copy Marked Changes". The only thing to be aware of is that you must copy every parent directory as well as the files of interest. For example, to copy the file /src/cmd/ws/wls.cpp, you'd select wls.cpp, but also the ws, cmd and src directories.

Once the copy completes, your target snapshot will have a reference to all copied files, as well as the full history of each file. You can now reorganize the directory hierarchy and unlink (or delete) any unused directories.

When you are satisfied with the new shared project, you might want to clean up references to the copied files in the original project. To do so, you can either delete or unlink the files from the original project. Before we continue, let's review the difference between unlink and delete.

Delete vs. Unlink

Delete removes a file and records the delete in the file history. You might wonder about that, since if the file is really gone, why does it still have history? Well, the file is not really gone. Rather it is simply marked deleted in the snapshot and consequently ignored by most operations. In fact, you can use the recoverable files filter to see deleted files, and even recover (undelete) them. In fact, the existence (or deleted) attribute is much like any other versioned attribute managed by SnapshotCM.

However, there are situations where you might want something different. For example, what if you really do want a file and all its history to go away? Or at least disappear from this snapshot? This is where the unlink operation comes in.

Unlink removes a file from a snapshot, but in a different way than does delete. Where delete adds a record to the file's history and updates the snapshot's file reference accordingly, unlink removes the association between a snapshot and a file. After unlink, the snapshot has no reference to the file at all. In fact, nothing is recorded in the file history during a unlink. For this reason, unlink is not recoverable except to the extent that file references can be copied back into the snapshot from another snapshot.

Now that we've reviewed delete and unlink, let's get back to splitting a project.

Cleaning Up After a Project Split

To clean up the now shared files from your old project, you can either delete them or unlink them. If you delete them, the action is recorded in the file history. As a result, the delete will propagate to other snapshots as promotes and updates are performed. This may be a good thing when splitting a project, since you don't want these files to be used in the original project any more. However, you should understand that should you ever want to copy other code to the same shared project in the future, these deletes will want to be copied as well. A bit of care will be needed to make sure such items are deselected before any such future copy is performed.

If you unlink them, the history remains clean. However, if you have multiple snapshots in the source project which contain references to these files, you will need to unlink them from all such snapshots. Whether delete or unlink is best depends on your circumstances.

Delete / Unlink Recommendations for Specific Project Split Scenarios

For a mature project which has had customer releases, we recommend using delete to clean up the original location. This way you preserve what actually happened for earlier releases.

For a new project without customer releases, a clean split using unlink may be better.

Of course, you may have some of both situations. You may have a mature project with some new code you decide later you want to put into a shared project. If the code in question has not been release previously, using unlink can be clean and effective.

When in doubt, we recommend using delete, since it is a recoverable operation.