The advanced technology in SnapshotCM simplifies tasks that used to be difficult, time-consuming or error-prone, while continuing to provide top-notch support for routine operations. This document describes user tasks, with the goal of helping new users more quickly learn SnapshotCM, while also providing insights to help an experienced user of SnapshotCM be even more productive. As always, feedback to support@truebluesoftware.com is welcomed.

Logging in to SnapshotCM

Before you can access SnapshotCM, the SnapshotCM administrator must create a SnapshotCM account for you to use. Typically, the SnapshotCM account name will be created to match your operating system account (login) name and you will not need to do any explicit SnapshotCM account name configuration. But if they are different, you can explicitly configure the SnapshotCM account to use by setting the SNAPSHOTCM_ACCOUNT environment variable. Note also that SnapshotCM account names are case insensitive. That is, kate, KATE and Kate are all equivalent SnapshotCM account names.

For example, Katelyn's operating system login account is kate on most of her systems, but is kkramer on some. Since her SnapshotCM account name (Kate) differs from her kkramer login, she will need to set the environment variable SNAPSHOTCM_ACCOUNT=kate on those systems.

Trusted Login Configuration

The operating system account (login) name is also visible in the Trusted Logins/Hosts list associated with each SnapshotCM account. In this list, the logins referred to are the operating system accounts from which trusted access to the given account is to be allowed. Continuing the previous example, to add trusted access to the Kate SnapshotCM account for the kkramer and kate OS logins, add two lines to the Trusted Logins/Hosts patterns for the Kate SnapshotCM account:

OS Login		Login/Host Pattern
kkramer		kkramer		host
kate		kate		host

Multiple entries for each OS login can be created if that facilitates defining appropriate host patterns. The GUI's help describes the wildcard patterns supported for these fields.

Understanding Workspaces

A workspace is a location on your local file system which is associated with the file hierarchy of a snapshot. In the SnapshotCM GUI, the association between files in your workspace and files in the associated snapshot is managed automatically. The GUI makes the choices for you. However, when operating from the command-line, much more flexibility is provided. The following discussion describes how the mapping works, the command-line options available, and how they can be used in various scenarios.

Most workspace commands need to know four things to operate: the server, the snapshot, the full path of the file in the snapshot and the full path of the file in the workspace. The last two are related in that the workspace root directory path plus the full path in the snapshot equals the full local path. For example, if the workspace root directory is C:\Work\WS and the full path in the snapshot is /src/cmd/file.cpp, then the full local path is C:\Work\WS\src\cmd\file.cpp. Given either one of these paths and the workspace root directory path, we can easily determine the other path.

The workspace mapping provides the association between a workspace hierarchy and a snapshot hierarchy. Workspaces normally associate the full hierarchy in a snapshot with a workspace, but on the command-line, it is possible to associate only a portion of the snapshot hierarchy with a workspace.

The first three uses assume you have not specified a workspace mapping on the command-line:

1. If you specify a relative path name and that relative path is within a workspace, the relative path is expanded to a full local path. Then the full local path is converted, via the workspace association, to a full path in the snapshot. Examples (C:\Work\WS is the root directory of the workspace):

   Parameter	Local Path	Path in Snapshot
   file.cpp	C:\Work\WS\src\cmd\file.cpp	/src/cmd/file.cpp
   h/file.h	C:\Work\WS\src\cmd\h\file.h	/src/cmd/h/file.h

2. If you specify a full path name and that path is within a workspace, the full path is converted, via the workspace association, to a full path in the snapshot. Examples:

   Local Path	Path in Snapshot
   C:\Work\WS\src\cmd\file.cpp	/src/cmd/file.cpp
   C:\Work\WS\src\cmd\h\file.h	/src/cmd/h/file.h

   When specifying local paths, SnapshotCM supports specifying files that reside in multiple workspaces. SnapshotCM chooses the workspace separately for each specified path so that each is checked out appropriately.

3. If you specify a full path and that path is not within a workspace (and it is a unix style path), then SnapshotCM treats it as a full path in the snapshot. The working directory is then used to determine which workspace to use to figure out where the local file should go. Examples (with working directory somewhere under C:\Work\WS, which is the assumed workspace root directory):

   Path in Snapshot	Local Path
   /src/cmd/file.cpp	C:\Work\WS\src\cmd\file.cpp
   /src/cmd/h/file.h	C:\Work\WS\src\cmd\h\file.h

4. If you specify a host and a snapshot (both required, either alone is ignored) on the command-line, then the workspace root directory is specified by the -D option and defaults to the current working directory if omitted. All other mappings are ignored. All file paths are treated as in 1, 2 or 3 above using the workspace specified on the command-line. Examples:

   Path Type	Example Command	Local Path	Path in Snapshot
   local relative	cd /tmp/src; wco -hhost -S/Project/Snapshot -D/tmp cmd	/tmp/src/cmd	/src/cmd
   local full	wco -hhost -S/Project/Snapshot -D/tmp /tmp/src/cmd/h/file.h	/tmp/src/cmd/h/file.h	/src/cmd/h/file.h
   snapshot full	wco -hhost -S/Project/Snapshot /src/cmd/file.cpp	$PWD/src/cmd/file.cpp	/src/cmd/file.cpp
   snapshot full	wco -hhost -S/Project/Snapshot /src	$PWD/src	/src
   snapshot full	wci -hhost -S/Project/Snapshot /src/cmd/h/file.h	$PWD/src/cmd/h/file.h	/src/cmd/h/file.h
   snapshot full	wco -hhost -S/Project/Snapshot -D/tmp /src/cmd/file.cpp	/tmp/src/cmd/file.cpp	/src/cmd/file.cpp
   snapshot full	wco -hhost -S/Project/Snapshot -D/tmp /src	/tmp/src	/src

5. Many commands support the -O option to allow operation between files in the -D specified directory (defaulting to the current directory) and a specified directory in the snapshot. In essence, this establishes a temporary and partial hierarchy mapping. The -O option requires that you specify full paths of files in the snapshot. All such paths are mapped onto the current directory. Examples:

   Example Command	Local Path	Path in Snapshot
   wco -O /src/cmd/file.cpp	$PWD/file.cpp	/src/cmd/file.cpp
   wci -O /src/cmd/h/file.h	$PWD/file.h	/src/cmd/h/file.h
   wco -O -hhost -S/Project/Snapshot /src/cmd/file.cpp	$PWD/file.cpp	/src/cmd/file.cpp
   wco -O -hhost -S/Project/Snapshot /src/cmd	$PWD	/src/cmd
   wco -O -hhost -S/Project/Snapshot -D/tmp /src	/tmp	/src
   wco -O -hhost -S/Project/Snapshot -D/tmp /src/cmd/file.cpp	/tmp/file.cpp	/src/cmd/file.cpp
   wci -O -hhost -S/Project/Snapshot -D/tmp /src/cmd/h/file.h	/tmp/file.h	/src/cmd/h/file.h

   If an explicit workspace is not specified, the -O option will use the workspace for the current directory, but get the file into the current directory rather than its normal location. When this occurs, the effect in the wls or GUI display can be interesting. We recommend using the -O option only with fully specified workspaces, and then running it outside a normal workspace.

6. The -o/Path option allows one to create a partial workspace association from /Path in the snapshot to the directory specified by the -D option (which defaults to the current directory).

Merge Scenarios

The simplest merge is the one no one has to do. Therefore we recommend structuring your work, as much as is practical, to avoid unnecessary merges. And when merges are likely, arrange for them to be trivial. Of course, sometimes merges are necessary or their benefit outweighs the cost. SnapshotCM handles merges of all attributes and in many cases, the merges are trivial and once selected, handled automatically. The following addresses those cases which are not so trivial.

Merge Types

Most often, when changes are copied from one snapshot to another, no merge will be necessary because an item will be changed in only one snapshot. That change will be copied automatically without conflict. Only when the same attribute is modified independently in two or more snapshots will a conflict occur. These parallel changes, or variants, require manual resolution. Parallel changes to all attributes other than file content can be resolved directly during the copy between snapshots. Parallel file content changes are merged using a variation of the check out, edit (merge), check in process used for normal content changes, though much of the task is automated.

Content Merging

When parallel changes are applied to the content of a file, one can choose one of the revisions to keep, or one can, for text files, merge the changes together to create a new, merged revision. In SnapshotCM, the results of a content merge are always stored in a file in a workspace, which can then be verified and modified as necessary before the results are checked in to a snapshot. Parallel changes can occur in two different scenarios discussed next.

Merge From a Snapshot into a Workspace

When you modify a file in your workspace, and then your snapshot is updated with other changes to that file, your local file becomes both modified (by you) and out-of-date (changed by someone else since you checked out the revision). You have three choices:

1. Select File->Merge (or invoke wmerge) to merge the snapshot changes into your local file and then edit the local file to examine the results and resolve any conflicts. Commit the merge results by check in.
2. Select File->Discard Local Changes (or run "wco -u") to discard your local changes and remove any lock.
3. Select File->Check In and select the force option (or run "wci -f") to force check in your changes and ignore changes in the snapshot (not recommended).

This scenario does not result in any branches in the file history.

Merge Between Snapshots

When parallel changes have been checked in (to different snapshots), a merge becomes necessary to combine the parallel content changes into one of the snapshots. In the Copy Changes dialog, a conflict will be identified by a double-ended red arrow. Clicking on the red arrow will bring up the Customize Resolution dialog box. While this dialog has many options for obscure conflict cases, the File Content: options of interest are shown on the left. The three most common options for resolving content conflicts are: Merge, Source and Target.

Once Merge, Source or Target is selected. Press OK or Apply to set this resolution method. Select Apply Changes to merge the parallel changes, together with the original base revision, into the named workspace and then edit the workspace file to examine the results and resolve any conflicts. From the command-line, use ssupdate or sscopy to perform the same selections.

Resolving Content Merge Conflicts using the Batch-mode Merge Tool

If you've configured a graphical merge tool, that tool will be used to resolve conflicts. The following discussion applies to the batch merge method. When the same region of a file is modified in different ways by both changes, the conflicting region will be bracketed in the workspace file. If a file region is modified by only one change, or is modified identically by both changes, it will not be bracketed. Bracketed conflicts must be manually resolved.

Bracketed conflicts will contain three versions of the conflicting region of text: the original version plus each of the changed versions. The versions of the region are separated by four different separator lines. An example will illustrate:

Non-conflicting lines before the
conflicting region.
<<<<<<< YOURS: FILE[1] + local changes.   
Your version of the region.
||||||| ORIGINAL: FILE[1]
Original version of the region.
=======
Other version of the region.
>>>>>>> THEIRS: FILE[2]
Non-conflicting lines after the
conflicting region.

<-- ===== Start of bracket =====
<-- Your local changed version 

<-- Original version of region

<-- Other parallel change  
<-- =========  End of bracket

Notice the complete conflict is bounded by the "<<<<<<<" and ">>>>>>>" separator lines. Searching for these lines will quickly locate bracketed conflicts. The first separator line identifies your version of the region (YOURS). In this example, it is FILE, revision 1 as modified in the local workspace. Next comes the ORIGINAL version of the region (the version from which the variants were created). It is FILE revision 1 in the example. Lastly comes the other changes (THEIRS), which is from FILE revision 2.

To resolve the conflict, you need to reduce each bracketed conflict in the file to one merged version without separator lines and then verify the results. That, of course, is an exercise left to the reader. :--)

Text and Binary Files In Your Workspace

Let's start this discussion with a definition of what distinguishes text and binary files. In SnapshotCM, text files are those files which will have end-of-line (EOL) translation performed on them during check in and check out, while binary files are those for which no EOL translation will be performed. EOL translation is necessary because the various operating systems of our day do not agree on how to store EOL indications in text files. SnapshotCM understands three EOL text formats: Unix, Windows and Mac. Unix systems use a single nuline character ('\n' or ascii 10), Windows systems use carriage return and nuline characters ("\r\n" or ascii 13 followed by ascii 10), and Macintosh systems use a single carriage return character ('\r' or ascii 13).

In order to allow seamless operation in such a mixed environment, SnapshotCM provides EOL text format translation on both check out and check in:

• On check out, SnapshotCM converts text files to the EOL text format of the target workspace.
• On check in, SnapshotCM converts text files into a canonical form for storing in the archive. SnapshotCM automatically detects and translates all three EOL text formats automatically on check in.

The net result is that any text file can be edited in any text format in any workspace and still be checked in without confusing SnapshotCM.

Workspaces and Remote File Systems

On check out, the format that is written is specified by the workspace mapping in effect. The workspace text format defaults to that of the execution platform, but can be set to other values. For example, using Samba or other remote file system, you can use the SnapshotCM Windows GUI to create and maintain a unix workspace. One simply need select the unix text format when creating the workspace and text files in that workspace will be written in unix format by all SnapshotCM tools.

Sharing Workspaces

With remote file system access, it may be tempting to share a workspace between systems with different EOL text formats. While we recommend setting up a workspace per platform, if all your tools on all your platforms can handle the same or both text formats involved, sharing a workspace will work. But if, for example, some Unix tools cannot handle Windows format and some Windows tools cannot handle Unix format, you will be setting yourself up for problems. Nevertheless, if such files need only be accessed from one system or the other, but not both, this can still work with a little care. For example, if most files are handled OK as unix format, that format can be used in the workspace and the few Windows-only format text files to be used only by Windows tools can be marked binary to disable the EOL text format conversions on check in and check out. As a binary file, the EOL characters will not be modified by SnapshotCM and the Windows tool can continue to get the desired format. This works as long as the Windows-only files need not be accessed by a tool that does not understand and preserve the format.

Shared Workspaces and Auto-home

If you have difficulties with SnapshotCM workspace mappings in an auto-home configuration, or if you are wanting to share a workspace between multiple machines, the following may be helpful.

1. Problem: In a shared home or auto-home environment, the workspace mapping file is shared and can store only one local workspace path for a given workspace mapping. But the paths to the workspace from the differing systems are not consistent.
   Solution 1: Force SnapshotCM to use a different workspace mapping file for each system by setting the SNAPSHOTCM_WMAP variable to a machine specific path. Example:

   export SNAPSHOTCM_WMAP=$HOME/.SnapshotCM.wmap.`uname -n`

   Solution 2: Create multiple workspace mappings in the shared workspace registry, one mapping for each system. The mappings will be identical except for a machine specific name and workspace path.
   Both of these solutions involve maintaining duplicate workspace mappings.

2. Problem: The auto-mount path to a workspace changes with each mount.
   Solution: Edit your mapping automatically in your login script. For example, you could run something like:

   cd workspace_root; wmap update -NWSNAME -D .

   
   Use "-D ." rather than "-D path" so that SnapshotCM can set a path that SnapshotCM commands will understand.

Return to top of document.

SnapshotCM Environment Variables

SnapshotCM provides several environment variables to customize behavior. In common use, none of these need be set.

SNAPSHOTCM_ACCOUNT

Set to the name of the SnapshotCM account to use to login to SnapshotCM. If undefined, clients will use the name of the account used to login to your client system. See Logging in to SnapshotCM for further discussion of the use of this variable.

SNAPSHOTCM_RC

Set to the full path name of the runtime configuration file used by the command-line tools to hold default options. If undefined, the commands use the path %HOMEDRIVE%%HOMEPATH%\.snapshotcmrc on Windows, and $HOME/.snapshotcmrc on Unix. See the wco manual page for further discussion of the use of this variable.

SNAPSHOTCM_WAN

Set to indicate the degree of compression to perform on traffic between the client and the server. A value of 0 disables compression. Values of 1 to 9 indicate the degree of compression, with smaller values favoring quick compression using little CPU or memory, and higher values favoring better compression at the cost of significantly more CPU and memory. If undefined, a value is chosen automatically based on the performance of the link between the client and server. For LAN environments, compression is typically disabled. For WAN or dial-up environments, compression is typically set to maximum. Setting this value to 0 on the client disables compression both to and from the server.

SNAPSHOTCM_WMAP

Set to the full path name of the workspace definition file. If undefined, clients use the path %USERPROFILE%\Application Data\SnapshotCM.wmap on Windows and $HOME/.SnapshotCM.wmap on Unix. Note that older releases used different default names.

Authentication Token

The authentication token is created in %HOMEDRIVE%%HOMEPATH%\.cm.<SnapshotAccountName>.<SnapshotServerName> on Windows and $HOME/.cm.<SnapshotAccountName>.<SnapshotServerName> on Unix. The authentication token is used to avoid the need to specify a password every time a command is used. If passwords are required for logging in, removing the authentication token file will force the next command to re-authenticate, which is a good thing to do when logging off for the day. The administrator can set the maximum lifetime of a token.

Return to top of document.

Enabling and Disabling SnapshotCM's SCC Integration on Windows

SnapshotCM integrates into Developer Studio and other tools using the SCC API, providing SnapshotCM operations directly from within these environments. This integration is installed and configured by the SnapshotCM installer on Windows. The following describes how to enable, restore or disable SnapshotCM's SCC integration.

To enable or restore SnapshotCM's SCC integration, load the SnapshotCM.reg file from SnapshotCM's install directory:

regedit "c:\Program Files\True Blue Software\SnapshotCM\SnapshotCM.reg"

To disable SnapshotCM's SCC integration, load the SCCDisable.reg file in SnapshotCM's install directory:

regedit "c:\Program Files\True Blue Software\SnapshotCM\SCCDisable.reg"

Return to top of document.

Removing Snapshots and Projects

If a SnapshotCM project or snapshot becomes uninteresting or obsolete, you can remove it. Since recovery from such deletion is not easy, SnapshotCM requires confirmation before performing such removal. And a couple of conditions must be satisified before a snapshot or project is removed:

1. To remove a snapshot, first remove all locks. The presumption is that a snapshot with locks is still active.
2. To remove a project, simply remove all snapshots from it.

The above operations can be performed via the GUI. The following unix shell script also can be used to remove a project. Customize appropriately.

# Remove snapshots in /Test project on host:

if [ $# -lt 1 ]; then
    echo "usage: $0 host ..." >&2
    exit 2
fi

for host in $*
do
    sslist -RHX -h $host /Test |             # list all snapshots in /Test project
        sort -r |
        while read ss
        do
            wset -quR -h $host -S "$ss" /    # Unlock all files
            ssremove -h $host "$ss"          # Remove snapshot
        done
done

Return to top of document.

SnapshotCM Error Messages

The following is a partial list of SnapshotCM error messages. Each message contains a description of the possible causes of the error, and a discussion of what to do next.

Cannot login to SnapshotCM account "user" on server "hostname": Unknown account

The SnapshotCM account user does not exist on host. See Logging in to SnapshotCM for a discussion of creating and accessing a SnapshotCM account.

Cannot login to SnapshotCM account "user" on server "hostname": Hostname lookup failed

Tthe IP address for the hostname could not be found. The most common cause for this message is that the SnapshotCM server hostname was mistyped, though this error can occur if DNS or other host name to IP address conversion functionality is mis-configured. To test your DNS configuration, run: nslookup hostname

/Item/Path: Destination directory does not exist in target snapshot.

The directory into which /Item/Path is to be copied does not exist in the target snapshot. This occurs when copying new items and a parent directory is not selected for copy, or fails to copy. It can also occur if the destination directory has been deleted from the target snapshot, in which case you can undelete it to enable the copy.
If on checking, you find that the destination directory does exist in the target snapshot, then it is likely that the directory was deleted and recreated, or a duplicate create of the directory was performed, causing the target directory to have a different history than the source directory. To resolve, either delete the target directory or rename the target directory out of the way, then undelete the original target directory (if it was deleted).

/Item/Path: Directory not empty

The directory cannot be deleted because it contains one or more files or directories. When copying to another snapshot, /Item/Path refers to the directory in the target snapshot

/Item/Path: New name already exists

When copying to another snapshot, a different item with the same directory and name already exists in the target snapshot. This can occur when a directory or item is created multiple times rather than being created once and then copied to the other snapshots. To resolve this in the case of a directory, rename one of the directories so it and its contained files can be copied into a single snapshot, then move all child items into a single directory. To avoid a dead-lock situation, do not delete the duplicate empty directory until the change has be propagated to all target snapshots. In the case of a file, simply rename one of the copies.

Return to top of document.