Workspace Filtering in SnapshotCM
Have you ever had a problem building because someone
forgot to check in all their changes? Or perhaps you've tested your code only
to find out that your workspace wasn't up-to-date! SnapshotCM helps make such a
frustrating waste of time a thing of the past.
SnapshotCM eliminates these and similar problems through its
task-oriented filters, as well as the ignore and auto-import filters. All these
filters serve to direct focus to files specific to a task. Two key benefits
result: First, you won't forget about a file relevant to the task, whether it
needs to be updated, checked in, or merged. And second, you won't
unintentionally act upon irrelevant files.
SnapshotCM's filtering comes in four forms: working sets,
the new ignore and import filters, and the view task filters. Together they
deliver the laser focus you need to be productive.
SnapshotCM's working set defines which versioned files and
directories belong in a workspace. It provides a simple, high-level way to keep
your workspace from being cluttered by parts of your project which are not of
concern to you. If your project is small and you want all files copied into
your workspace, you can safely ignore the working set as the default includes
You define a working set by selecting directory hierarchies
to include and exclude. A longer path overrides a shorter path. For example,
using the CLI syntax, -I/ -E/test includes (-I) all files below the
root directory except (-E) /test. The GUI provides a checkable
hierarchy showing visually what is selected and omitted.
While straightforward, one case needs additional
clarification: How does SnapshotCM treat versioned files which are excluded by
the working set but already checked out into the workspace? This can happen by
applying a working set to an already populated workspace, or by explicit check
out of non-working set files.
In both cases, existing workspace files excluded by the
working set are treated just as if they were part of the working set. You can
modify and check in any changes, and if such files are out-of-date, they will
be updated by the workspace update action.
In short, workspace update acts upon all items in the
working set, as well as any versioned files already existing in the
SnapshotCM's ignore filter suppresses action and display of
files matching the filter. Unlike the working set which defines the set of
files you care about at a high level, ignore filtering efficiently ignores
files that cut across many directories, such as all Release and Debug
directories, or all Makefile and .o files.
The ignore filter applies to all workspace commands, though
it can be disabled or overridden using the option -j'*|*/'. In the Workspace
Browser, two check boxes enable filtering for versioned and workspace
Checking Filtered in the Workspace View
applies the ignore filter to all files in the Workspace View, as well as
non-versioned (local-only) folders in the Folders view.
Checking Filtered in the Snapshot View applies
the ignore filter to all versioned files and folders in all views. Two things
to clarify. First, it applies the ignore filter only to versioned files.
It does not filter local-only files and folders. Second, it filters versioned
files from all views (including the Folders and Workspace Views).
SnapshotCM provides this filter primarily to ignore platform-specific files in
a multi-platform environment. For example, ignoring Makefiles on Windows, and
Visual Studio project and solution files on unix.
View or edit the ignore filter by selecting the
Filters... button on the Workspace Manager dialog, or by
selecting the File->Filter/Ignore->Advanced menu. Alternatively,
the wmap command provides several
options for viewing and editing the filter. The ignore filter applies to all of
a user's workspaces on a system.
The Import Filter automatically finds and marks matching
files for import. Marked files then appear in the Workspace Browser with a
check in action icon so you don't forget to import them when ready.
If the import filter automatically marks a file for import
that you don't want to import, you have two choices. You can either update your
import or ignore filters to unselect the file. Alternatively, if a true
exception, use the Unmark for Import menu action to remove the mark. In
the latter case, SnapshotCM will remember your action as long as the file
remains in the workspace. If you remove the file and later recreate it,
SnapshotCM will once again mark it for import.
View or edit the import filter by selecting the
Filters... button on the Workspace Manager dialog. Alternatively,
the wmap command provides several
options for viewing and editing the import filter. The import filter applies to
all of a user's workspaces on a system.
Interaction of Import and Ignore Filters
When a file matches both the import and ignore filters,
SnapshotCM ignores it. Files in an ignored folder are also ignored, even if
matching the import filter. For example, if you ignore the Release/ directory,
files matching the import filter but inside the Release/ directory hierarchy
will be ignored. Similarly, you can select to import all *.[ch] files and
ignore *.tab.[ch] files which will mark for import all C files except yacc
After a file is automatically marked for import, if the
import or ignore filter is edited such that the file would no longer be marked,
SnapshotCM automatically unmarks it. Files which are manually marked or
unmarked are not affected by the auto-mark algorithms.
View Task Filters
The SnapshotCM View Filters provide task oriented file
filtering. SnapshotCM dynamically displays matching files, incorporating
changes as they happen. This way, you always see up-to-date information.
SnapshotCM provides the following filters:
- View All Files
- View Out-of-date Files
- View Files Not in Snapshot (or Workspace)
- View Files in Snapshot (or Workspace)
- View Recoverable Files
- View Locked Files
- View My Locked Files
- View Files Needing Action
- View Files Needing Check In
- View Files Needing Merge
- View Filtered Files
A extra word about the last one. View Filtered Files
shows the files normally hidden by the ignore filter. It acts like View All
Files and the negation of the ignore filter.
A popular configuration sets the View Files Needing
Action Recursively filter in the Workspace View, adds common file
types to the Import Filter, and intermediate files and directories to
the ignore filter. This way, new files you care about appear automatically and
files you don't care about are ignored without any additional action being
The filters are highly efficient. Nevertheless, for very
large workspaces, the following actions may improve your run-time
The slowest step in displaying a workspace is traversing the
workspace hierarchy checking the state of the local files. Therefore faster
refreshes primarily result from reducing the number of files and folders
traversed in your local workspace. The following steps describe how to do
Use the working set to reduce the number of versioned
files populated into your workspace. To do this, select your workspace and
invoke Workspace->Properties to open the workspace definition. Then
select the Working Set tab and uncheck directory hierarchies you don't
need. Save any changes by selecting OK.
Next, open your workspace and in the Workspace
View, select View Files in Snapshot Recursively Filtered. Remove any
directory hierarchies from the Workspace View which you've excluded from the
working set. Once removed, they will disappear from view. If they continue to
appear in the view after removal, then the working set is not excluding
After finishing with working set changes, in the
Workspace View, select View Files Not in Snapshot Recursively
Filtered. Review the listed folders for candidates for filtering, then use
the File->Filter/Ignore menu to ignore non-versioned folders such as build
intermediate folders. (For example, Release/ and Debug/ folders as used by
Once that's done, then ignore intermediate files
extensions that are still showing. Since ignored workspace folders and files
are not traversed or examined, ignoring these items can make a big difference
in workspace performance. It's best to do this step in a fully built
Switching to the Snapshot View, select View
Files in Workspace Recursively Filtered. Use the File->Filter/Ignore
menu to ignore versioned folders and files which are unnecessary. An example is
build files for a different platform, such as Makefiles on Windows and Visual
Studio build files on Linux.
Continuing in the Snapshot View, select View
All Filtered Files Recursively. Confirm that the displayed files and
folders are not required to be in your workspace, then select File->Delete,
uncheck "From snapshot" and check "From workspace" and "Folders recursively."
Be careful not to remove these files from your snapshot! Since you are
invoking the delete from the Snapshot View, you do not want the default
delete action! The idea is to clean out of your workspace those versioned
files you don't need to be there and which you are now ignoring.
At this point, some removed files and folders may show
as needing check out. You can ignore this.
You are done cleaning your workspace. Verify that you
didn't remove any needed files by rebuilding your workspace.
We suggest that in the Workspace View you select
View Files Needing Action Recursively Filtered, and in the Snapshot
View you select View All Files Filtered.
SnapshotCM provides the powerful filtering that helps you be
productive. By showing you just what's relevant to your task, you will
efficiently and accurately complete your version control activities.