SnapshotCM User Guide

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.

Index:

• Logging in to SnapshotCM
• Understanding Workspaces
• Merge Scenarios
  • Merge Types
  • Content Merging
  • Resolving Content Merge Conflicts
• Text and Binary Files In Your Workspace
• Shared Workspaces and Auto-home
• Environment Variables
• Enabling and Disabling SnapshotCM's SCC Integration
• Removing Snapshots and Projects
• SnapshotCM Error Messages

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 hierarchies of one or more snapshots. A workspace definition (or mapping) specifies several pieces of information:

The workspace root location specifies the root of a workspace, which is a local file system hierarchy containing files managed by SnapshotCM.

A workspace name is any unique name identifying the workspace.

A workspace working set specifies the portion of all files and directories that you wish to have in the workspace. It consists of a set of include and exclude paths, the most specific of which takes priority. Paths are full paths (beginning with a slash) and are relative to the workspace root. Note: In releases which only supported mapping all of a single snapshot, workspace and snapshot file paths were equivalent. However, now that multiple snapshot mappings to a single workspace are supported, a snapshot's file path is no longer unique. Hence, the workspace path is now used.

A mount location specifies the workspace path where a snapshot's file hierarchy is mounted. Each mount defines how one snapshot fits into the workspace.

The mount host & snapshot define the repository server and snapshot to mount.

The snapshot directory specifies the directory within the snapshot to map. Typically, the root directory (all of a snapshot) is selected.

The locking mode specifies whether to keep a versioned file read-only unless locked, which is the traditional locking method to serialize changes with other users sharing the same snapshot, or to leave them always writable, which requires local merges to serialize concurrent changes by other users.

The text file end-of-line mode defines how to translate end-of-lines for text files.

Once a workspace is defined, SnapshotCM needs no specifications other than what operations to perform on which files. In the GUI, files are directly selected. In the command-line, the normal case is to give the local file names for the files to operate upon. Such names can be relative or full file system paths. However, the command-line allows more flexibility which we discuss next.

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. When operating on files in a workspace, relative file names are converted to full local paths and looked up in the workspace definition to determine the server, the snapshot, and the path in the snapshot. When a full file system path is given, it is used directly for look up.

It is also possible to provide a workspace path, which is the path in the workspace relative to the root of the workspace. It always begins with a slash. However, a workspace path alone is not sufficient, because it does not identify which workspace to operate upon. Workspace commands use the current working directory to determine the workspace when given a workspace path.

However, there is a potential ambiguity in interpreting full paths. This arises because a full path can be interpreted as a local path to a file in a directory, or as a workspace path relative to the workspace root. This ambiguity is resolved by assuming first that it is a local path, and if that path extends into a workspace, it is used as such. If the path does not reference a workspace and the current directory is in a workspace, then the path is understood as a workspace path. Why support this ambiguity? It is true that local paths are sufficient. However, it is convenient to be able do some operations by full path. For example, to list all files in the current workspace (selected by your working directory), one simply runs "wlsr /". Otherwise, the command is either "wlsr C:/long/path/to/workspace/root" or "wlsr ../../..", and you have to know where you are to enter the appropriate relative path to get to the workspace root.

Command-line Workspace Specification

Command-line path interpretation is further complicated by the ability to explicitly define a workspace on the command-line. If an existing workspace is referenced (using -N workspace), then path interpretation is as for implicitly found workspaces, except that workspace paths do not require that the current directory be in the target workspace. The following describes handling of paths. The following workspace definition is assumed:

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 definition, to full paths in the workspace and snapshot. Examples (C:\Work\WS\Morpheus\src is the current directory):

   Parameter	Local Path	Path in Workspace	Path in Snapshot
   cmd/file.cpp	C:\Work\WS\Morpheus\src\cmd\file.cpp	/Morpheus/src/cmd/file.cpp	/src/cmd/file.cpp
   ../../Monsoon/file.h	C:\Work\WS\Monsoon\file.h	/Monsoon/file.h	/monsoon/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 Workspace	Path in Snapshot
   C:\Work\WS\Morpheus\src\cmd\file.cpp	/Morpheus/src/cmd/file.cpp	/src/cmd/file.cpp
   C:\Work\WS\Monsoon\file.h	/Monsoon/file.h	/monsoon/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 workspace. 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 in our example workspace):

   Path in Snapshot	Local Path
   /Morpheus/src/cmd/file.cpp	C:\Work\WS\Morpheus\src\cmd\file.cpp
   /Monsoon/file.h	C:\Work\WS\Monsoon\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 workspace and 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	$PWD/src	/src
   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 -D/tmp /src	/tmp/src	/src
   snapshot full	wco -hhost -S/Project/Snapshot -D/tmp /src/cmd/file.cpp	/tmp/src/cmd/file.cpp	/src/cmd/file.cpp

5. 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 in different ways in two or more snapshots will a conflict occur. These parallel changes 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 further as necessary before the merged result is 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. After the merge, your local file differs from the snapshot file only in your local changes.
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

For most users in most situations, SnapshotCM's handling of text and binary files just works. The user does nothing special and everything works the way they expect. Yet, there are specialized situations where one requires a clear understanding of how SnapshotCM treats text and binary files differently. Read on for the details!

Text and Binary Defined

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).

What's the Difference in Handling

In SnapshotCM, text and binary files are treated differently in two ways:

1. On check out, text files will have their end-of-line (EOL) characters edited to match the workspace EOL setting, while no EOL character editing occurs for binary files. The workspace defines which of the EOL formats is written.
2. On check in and import, EOL characters in text files are edited into a canonical form. All supported EOL sequences ("\n", "\r\n" and "\r") in the file will be converted to canonical form. The net result is that any text file can be edited in any EOL text format in any workspace and still be checked in without confusing SnapshotCM.

The server treats text and binary files identically, as it does no content editing at all.

Automatic Text / Binary Type Determination

At import, a file is scanned for signs of it being binary as well as for signs of it being a reasonable text file. For example, files with any bytes with values 00 through 05 are considered to be binary. Similarly files with regular end-of-line characters are considered to be text. If there are signs a file is binary, or no signs of it being text, it is treated as a binary file.

The one common situation where this can do the "wrong" thing is with a zero length file which has no data to examine. SnapshotCM sets a binary file type when importing a zero length file.

Another situation where you might need to override the default is when you have text files used in a multiplatform environment, where the end-of-line sequence must remain fixed. In this case, one can force import as binary to prevent EOL editing by SnapshotCM.

If EOL editing is inappropriate for a file that otherwise appears to be text, it should be explicitly set to binary type during import.

You can override SnapshotCM's defaults at import time and force a binary import in the GUI by selecting the "Force binary import" check box in the Import dialog. You also can explicitly select binary or text during a command-line import using the wci command.

Once imported, the type also can be changed, though beware that importing a binary file as text can irreversably corrupt it.

Summary

SnapshotCM simply does the right thing for text and binary file handling for most situations. And it provides the capabilities you need to handle those special cases should they arise.

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.

Text / Binary and Shared Workspaces

Using Samba, NFS, or the like, it's possible to access a workspace residing on a remote file system, even using the Windows GUI to manage a Linux workspace. When setting this up, be aware of the following issues:

• Each system accessing a workspace should have a consistent definition for the workspace mounts. Specifically, every shared mount must be mounted in the same location, have the same text file end-of-line mode, the same concurrent/locking value, and mount the same directory in the snapshot. It's expected that the general workspace values such as path to the workspace, the workspace name and even the working set may be different, but the shared mount definitions must be identical. It is also OK to mount a subset of all mounts in a shared workspace. But those which are mounted, must be consistent with all other uses.
• File permissions need to be such that the user from either system can access the files of the workspace, including the SnapshotCM cache associated with each workspace.
• The SnapshotCM cache is stored in the .cache.SnapshotCM file in the root of a mount on most systems. If running on Windows with the workspace on an NTFS file system, SnapshotCM will use an Alternate Data Stream (ADS) file attached to the root directory of a mount to store the cache. Since ADS files are not generally accessible remotely, to share the cache file in this case, you must force it to be stored in a normal file named .cache.SnapshotCM. You can do this by setting the SNAPSHOTCM_DISABLE_ADS environment variable. There is also a hidden flag to disable ADS in the workspace definition, which can be useful to preserve ADS use for non-shared workspaces. Contact support for details on configuring this, as it involves manual editing of the workspace definition.

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 will resolve 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_DISABLE_ADS

If set, disables use of Alternate Data Stream files for storing the cache for a workspace mount. Normally, an ADS file is used if available (running on Windows with workspace on an NTFS file system).

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 IDEs using the Microsoft Source Code Control (MSSCC) 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 MSSCC integration.

To enable or restore SnapshotCM's MSSCC 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 MSSCC 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.