SnapshotCM In Depth: Workspace File State

SnapshotCM automatically determines the state of your workspace files, and uses this to guide users in the normal flow of change and to help avoid errors. SnapshotCM does this by displaying action icons showing what needs to happen to a file, and by enabling action buttons to do those actions. Workspace files can be in one of five states:

1. up-to-date: This simply means that the file in your workspace exactly matches the file in the associated snapshot. This state results from checking out a file. Lock and edit are normal actions when in this state.
2. modified: The workspace copy is modified from what was checked out. Edit, Diff and Check in are normal actions in this state.
3. out-of-date: The snapshot revision of the file has changed since the workspace copy was checked out. Update is the normal action in this state.
4. merge-required: Both the snapshot revision and the local file have changed since the workspace copy was checked out. Merge and Edit are the normal actions in this state, with Undo Check Out and Check in less common.
5. unknown: SnapshotCM does not have the file's check out information.

SnapshotCM caches information during a check out to allow quickly and efficiently determining and tracking a file's state. States 1 - 4 are the normal states associated with a file. However, when the cached check out information is missing, files are put into an unknown state*.

When first detecting the unknown state, SnapshotCM attempts to recreate the cache information by doing a background check out and compare of the snapshot file with the workspace copy. If identical, the up-to-date state information is recorded in the cache and the unknown state is resolved as up-to-date. Otherwise, if the user has the file locked in the current workspace and the workspace copy is writable, then SnapshotCM assumes that the workspace copy is modified and updates the cache accordingly. Note that this assumption can be wrong. If neither of these cases applies, the unknown state remains.

SnapshotCM displays a question mark icon for unknown state files, and treats them much like it does files in the merge-required state: Workspace update, normal check in, and normal check out operations warn about, but do not act upon, such files. And like the merge-required state, SnapshotCM requires explicit user action to resolve the unknown state. Resolution actions are:

• Undo Check Out (wco -u) to replace the workspace copy with the snapshot revision. A .bak file is created from the workspace copy.
• Check In (wci -f) to create a new snapshot revision from the workspace copy.
• Merge (wmerge) to perform a 2-way merge of the file copies. When the merge result is saved, the state will be recorded as modified, so that a normal check in can occur.

While the unknown state is not common, SnapshotCM resolves it automatically in the most common cases, and when that's impossible, makes it straightforward for users to understand and resolve it manually.

* The cached check out information can be missing for many reasons, including the file was generated or copied into a workspace rather than being checked out, the file was temporarily renamed and SnapshotCM noticed so removed the check out information, the cache file was explicitly removed, coding defects, etc.